loki-mode 7.78.0 → 7.80.0

package/autonomy/loki

@@ -125,6 +125,16 @@ if [ -f "$_LOKI_SCRIPT_DIR/lib/git-pr-advisory.sh" ]; then
     source "$_LOKI_SCRIPT_DIR/lib/git-pr-advisory.sh"
 fi
 
+# Unified config-file support (#691). Canonical LOKI_CONFIG_MAP + the config-file
+# loader (loki_maybe_apply_config_file / loki_apply_config_file) and the
+# example/schema/validate generators. Side-effect-free on source: defines the
+# array + functions, exports nothing. The main() pre-pass and run.sh's YAML
+# parsers both call into this single lib so the mapping cannot drift.
+if [ -f "$_LOKI_SCRIPT_DIR/lib/config-map.sh" ]; then
+    # shellcheck source=autonomy/lib/config-map.sh
+    source "$_LOKI_SCRIPT_DIR/lib/config-map.sh"
+fi
+
 # Resolve the script's real path (handles symlinks)
 resolve_script_path() {
     local script="$1"
@@ -1473,6 +1483,24 @@ cmd_start() {
                 issue_mode_args+=("--detach")
                 shift
                 ;;
+            # #691: unified config-file aliases. Already applied by the main()
+            # pre-pass (loki_maybe_apply_config_file); these arms only consume
+            # the flag+path so the loop does not misread the path as the PRD
+            # positional, and do NOT forward it to the run.sh exec target.
+            --config|--vars|--env-file)
+                # Guard the shift 2: a dangling flag (path omitted, flag is the
+                # last arg) would underflow shift 2 and, under set -euo pipefail,
+                # abort the command SILENTLY. Give an honest actionable error.
+                if [ "$#" -ge 2 ]; then
+                    shift 2
+                else
+                    echo "loki: $1 requires a file path (e.g. --config .loki/config.yaml)" >&2
+                    exit 1
+                fi
+                ;;
+            --config=*|--vars=*|--env-file=*)
+                shift
+                ;;
             -*)
                 echo -e "${RED}Unknown option: $1${NC}"
                 exit 1
@@ -2899,6 +2927,133 @@ cmd_resume() {
     fi
 }
 
+# loki why -- actionable failure/outcome diagnosis (B5).
+# Reads the already-captured run artifacts (no new state): the terminal run state
+# (.loki/<autonomy-state>.json: status, lastExitCode, iterationCount), the durable
+# completion record (.loki/state/completion.json: outcome, branch, files, pr_url),
+# and the latest structured handoff (.loki/memory/handoffs/*.md). Produces an
+# honest "what happened + what to do" report. Read-only; never fabricates -- if a
+# field was not captured it says so. --json emits the machine-readable record.
+cmd_why() {
+    local as_json=0
+    case "${1:-}" in
+        --json) as_json=1 ;;
+        --help|-h) echo "Usage: loki why [--json]  -- explain the last build's outcome and what to do next"; return 0 ;;
+        "" ) : ;;
+        *) echo -e "${RED}Unknown flag: $1${NC}"; echo "Usage: loki why [--json]"; return 1 ;;
+    esac
+
+    local loki_dir="${LOKI_DIR:-.loki}"
+    # Session-namespaced state when LOKI_SESSION_ID is set (mirrors run.sh A6).
+    local state_file="$loki_dir/autonomy-state.json"
+    if [ -n "${LOKI_SESSION_ID:-}" ] && [ -f "$loki_dir/sessions/${LOKI_SESSION_ID}/autonomy-state.json" ]; then
+        state_file="$loki_dir/sessions/${LOKI_SESSION_ID}/autonomy-state.json"
+    fi
+    local completion_file="$loki_dir/state/completion.json"
+
+    if [ ! -f "$state_file" ] && [ ! -f "$completion_file" ]; then
+        echo "loki why: no run found here yet (no $state_file or $completion_file)." >&2
+        echo "Run a build first: loki start <spec>" >&2
+        return 1
+    fi
+
+    if [ "$as_json" = "1" ]; then
+        _LOKI_WHY_STATE="$state_file" _LOKI_WHY_COMPLETION="$completion_file" python3 - <<'WHYJSON'
+import json, os
+def load(p):
+    try:
+        with open(p) as f: return json.load(f)
+    except Exception: return {}
+state = load(os.environ.get("_LOKI_WHY_STATE", ""))
+comp = load(os.environ.get("_LOKI_WHY_COMPLETION", ""))
+print(json.dumps({"state": state, "completion": comp}, indent=2))
+WHYJSON
+        return 0
+    fi
+
+    # Human-readable report. The diagnosis maps the terminal status to a plain
+    # explanation + a concrete next action; everything is sourced from the files,
+    # nothing is invented.
+    _LOKI_WHY_STATE="$state_file" _LOKI_WHY_COMPLETION="$completion_file" \
+    _LOKI_WHY_HANDOFFS="$loki_dir/memory/handoffs" python3 - <<'WHYTXT'
+import json, os, glob
+def load(p):
+    try:
+        with open(p) as f: return json.load(f)
+    except Exception: return {}
+state = load(os.environ.get("_LOKI_WHY_STATE", ""))
+comp = load(os.environ.get("_LOKI_WHY_COMPLETION", ""))
+status = state.get("status") or comp.get("outcome") or "unknown"
+exit_code = state.get("lastExitCode")
+iters = state.get("iterationCount")
+
+# status -> (one-line meaning, suggested next action). Honest + specific.
+GUIDE = {
+    "council_approved": ("The completion council agreed the work is done and verified.",
+                         "Review the diff and open a PR (git push + gh pr create, or LOKI_AUTO_PR=1)."),
+    "council_force_approved": ("Completion was force-approved (council could not fully converge).",
+                               "Review the diff carefully before merging -- convergence was not unanimous."),
+    "completion_promise_fulfilled": ("The agent declared its explicit completion promise fulfilled.",
+                                     "Verify the promised outcome, then review and PR."),
+    "max_iterations_reached": ("The build hit the iteration cap before the council approved it.",
+                               "Inspect what is left (loki status), raise LOKI_MAX_ITERATIONS or narrow the spec, and resume."),
+    "max_retries_exceeded": ("The build exhausted its retry budget on a repeating failure.",
+                             "Read .loki/logs for the recurring error (rate limit? failing test?), fix the root cause, then re-run."),
+    "failed": ("The build ended in a failure state.",
+               "Read .loki/logs/ + the handoff below for the failure, fix it, then re-run."),
+    "policy_blocked": ("A policy/trust gate blocked completion.",
+                       "Review the blocking finding; address it or use the documented override path."),
+    "budget_exceeded": ("The cost budget breaker paused the build.",
+                        "Raise LOKI_BUDGET_LIMIT or accept the partial result, then resume."),
+    "paused": ("The build is paused (human-intervention signal).",
+               "Resume with: loki resume."),
+    "interrupted": ("The build was interrupted before a terminal state.",
+                    "Resume with: loki resume."),
+    "stopped": ("The build was stopped by the operator.",
+                "Start a new build with loki start, or resume if you meant to continue."),
+    "force_stopped": ("The build was force-stopped.",
+                      "Start a new build, or investigate why a force-stop was needed."),
+    "running": ("The recorded state says a build is still running (or crashed mid-run).",
+                "If no build is active it likely crashed; in durable mode (LOKI_DURABLE_STATE=1) a restart resumes, else loki start re-runs."),
+}
+meaning, action = GUIDE.get(status, ("No diagnosis mapping for this status; see the raw fields below.",
+                                     "Check loki status and .loki/logs/ for detail."))
+
+print("Loki: why")
+print("=" * 60)
+print(f"  Outcome     : {status}")
+if exit_code is not None:
+    print(f"  Exit code   : {exit_code}")
+if iters is not None:
+    print(f"  Iterations  : {iters}")
+if comp.get("branch"):
+    print(f"  Branch      : {comp['branch']}")
+if comp.get("files_changed") is not None:
+    print(f"  Changes     : {comp.get('files_changed',0)} files (+{comp.get('insertions',0)}/-{comp.get('deletions',0)})")
+if comp.get("pr_url"):
+    print(f"  PR          : {comp['pr_url']}")
+print()
+print(f"  What happened: {meaning}")
+print(f"  What to do   : {action}")
+
+# Surface the latest structured handoff (already-captured context), honestly.
+hd = sorted(glob.glob(os.path.join(os.environ.get("_LOKI_WHY_HANDOFFS",""), "*.md")))
+if hd:
+    print()
+    print(f"  Latest handoff: {hd[-1]}")
+    try:
+        with open(hd[-1]) as f:
+            head = "".join(f.readlines()[:8]).rstrip()
+        for line in head.splitlines():
+            print(f"    {line}")
+    except Exception:
+        pass
+print()
+print("  (loki why --json for the raw record; loki status for live state.)")
+WHYTXT
+    return 0
+}
+
 # Show current status
 cmd_status() {
     # Check for flags
@@ -6701,6 +6856,21 @@ cmd_run() {
                 run_detached=true
                 shift
                 ;;
+            # #691: unified config-file aliases. Applied by the main() pre-pass;
+            # consume here so the path is not misread as the issue-ref positional
+            # and is not forwarded to cmd_start.
+            --config|--vars|--env-file)
+                # Guard shift 2 against a dangling flag (silent set -e abort).
+                if [ "$#" -ge 2 ]; then
+                    shift 2
+                else
+                    echo "loki: $1 requires a file path (e.g. --config .loki/config.yaml)" >&2
+                    exit 1
+                fi
+                ;;
+            --config=*|--vars=*|--env-file=*)
+                shift
+                ;;
             -*)
                 echo -e "${RED}Unknown option: $1${NC}"
                 echo "Run 'loki run --help' for usage."
@@ -8109,15 +8279,27 @@ cmd_config() {
         get)
             cmd_config_get "$@"
             ;;
+        example)
+            cmd_config_example "$@"
+            ;;
+        schema)
+            cmd_config_schema "$@"
+            ;;
+        validate)
+            cmd_config_validate "$@"
+            ;;
         *)
-            echo -e "${YELLOW}Usage: loki config [show|init|edit|path|set|get]${NC}"
-            echo ""
-            echo "  show           Show current configuration (default)"
-            echo "  init           Create a config file from template"
-            echo "  edit           Open config file in editor"
-            echo "  path           Show config file paths"
-            echo "  set KEY VALUE  Set a configuration value"
-            echo "  get KEY        Get a configuration value"
+            echo -e "${YELLOW}Usage: loki config [show|init|edit|path|set|get|example|schema|validate]${NC}"
+            echo ""
+            echo "  show            Show current configuration (default)"
+            echo "  init            Create a config file from template"
+            echo "  edit            Open config file in editor"
+            echo "  path            Show config file paths"
+            echo "  set KEY VALUE   Set a configuration value"
+            echo "  get KEY         Get a configuration value"
+            echo "  example         Print an annotated config template (for --config)"
+            echo "  schema          Print the key -> env-var mapping table"
+            echo "  validate FILE   Validate a config file (--config) without applying it"
             echo ""
             echo "Settable keys (v6.0.0):"
             echo "  maxTier              Cost ceiling: opus, sonnet, haiku (default: opus)"
@@ -8295,6 +8477,41 @@ SET_CONFIG
     esac
 }
 
+# #691: print an annotated config template generated from LOKI_CONFIG_MAP, so it
+# can never drift from the parsers. Suitable for `loki start --config <path>`.
+cmd_config_example() {
+    if ! declare -f loki_config_generate_example >/dev/null 2>&1; then
+        echo -e "${RED}config example: config-map.sh helper not loaded${NC}" >&2
+        return 1
+    fi
+    loki_config_generate_example
+}
+
+# #691: print the machine-readable key -> LOKI_ENV_VAR mapping table.
+cmd_config_schema() {
+    if ! declare -f loki_config_generate_schema >/dev/null 2>&1; then
+        echo -e "${RED}config schema: config-map.sh helper not loaded${NC}" >&2
+        return 1
+    fi
+    loki_config_generate_schema
+}
+
+# #691: validate a config file (--config) WITHOUT applying it. Reports
+# unresolved ${VAR} refs, raw-secret literals (error), and per-value validation
+# failures. Non-zero exit on any failure.
+cmd_config_validate() {
+    local file="${1:-}"
+    if [ -z "$file" ]; then
+        echo -e "${RED}Usage: loki config validate <file>${NC}" >&2
+        return 2
+    fi
+    if ! declare -f loki_config_validate_file >/dev/null 2>&1; then
+        echo -e "${RED}config validate: config-map.sh helper not loaded${NC}" >&2
+        return 1
+    fi
+    loki_config_validate_file "$file"
+}
+
 # v6.0.0: Get a configuration value
 cmd_config_get() {
     local key="${1:-}"
@@ -10820,6 +11037,25 @@ cmd_quick() {
         fi
     fi
 
+    # #691: drop the unified config-file aliases from the task description. The
+    # main() pre-pass already applied the file; without this, a trailing
+    # `--config f.env` would be swept into task_desc (cmd_quick has no arg loop).
+    local _quick_args=()
+    local _skip_next=false
+    local _qa
+    for _qa in "$@"; do
+        if [ "$_skip_next" = "true" ]; then
+            _skip_next=false
+            continue
+        fi
+        case "$_qa" in
+            --config|--vars|--env-file)        _skip_next=true; continue ;;
+            --config=*|--vars=*|--env-file=*)   continue ;;
+        esac
+        _quick_args+=("$_qa")
+    done
+    set -- "${_quick_args[@]+"${_quick_args[@]}"}"
+
     local task_desc="$*"
     local version=$(get_version)
     local max_iter="${LOKI_MAX_ITERATIONS:-3}"
@@ -15306,6 +15542,32 @@ main() {
     # runs for the 8 ported commands). Marker file: ~/.loki-first-run.
     loki_telemetry "cli_command" "command=$command" 2>/dev/null || true
 
+    # Unified config-file pre-pass (#691). For session commands ONLY, honor
+    # LOKI_CONFIG_FILE / --config|--vars|--env-file and load the file BEFORE the
+    # per-command arg loop runs. Running here means: config exports survive the
+    # exec into run.sh, and the subsequent CLI arg loop still overrides them
+    # (CLI > config). The pre-pass SCANS without consuming; the per-command
+    # loops carry consume-and-ignore arms for the three aliases. Gated to
+    # start/run/quick so status/config/stop never trigger a config load.
+    case "$command" in
+        start|run|quick)
+            if declare -f loki_maybe_apply_config_file >/dev/null 2>&1; then
+                loki_maybe_apply_config_file "$@"
+            fi
+            # #691: documented observation hook. When LOKI_CONFIG_DUMP=1, print
+            # the resolved LOKI_* environment (after the config pre-pass AND any
+            # ambient env) and exit 0 WITHOUT running a build. Lets operators and
+            # tests verify exactly which values a --config file resolves to,
+            # without spend. The per-command CLI arg loops do not run on this
+            # path, so CLI-flag overrides are NOT reflected by the dump; it shows
+            # the config+env resolution only.
+            if [ "${LOKI_CONFIG_DUMP:-}" = "1" ]; then
+                env | grep -E '^LOKI_' | LC_ALL=C sort
+                exit 0
+            fi
+            ;;
+    esac
+
     case "$command" in
         run)
             cmd_run "$@"
@@ -15346,6 +15608,9 @@ main() {
         status)
             cmd_status "$@"
             ;;
+        why)
+            cmd_why "$@"
+            ;;
         stats)
             # CLI consolidation (Phase A): 'stats' is a deprecated alias of
             # 'report session'. On the Bun route this arm is never reached