loki-mode 7.19.1 → 7.19.2

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-to-product system. Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product via the RARV-C closure loop, with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.19.1
+# Loki Mode v7.19.2
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -383,4 +383,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.19.1 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.19.2 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.19.1
+7.19.2

package/autonomy/completion-council.sh

@@ -28,6 +28,10 @@
 #   LOKI_COUNCIL_CONVERGENCE_WINDOW - Iterations to track for convergence (default: 3)
 #   LOKI_COUNCIL_STAGNATION_LIMIT - Max iterations with no git changes (default: 5)
 #   LOKI_COUNCIL_DONE_SIGNAL_LIMIT - Max total done signals before force stop (default: 10)
+#   LOKI_UNCERTAINTY_ESCALATION   - Proactive stuck-escalation decision (default: 1; set 0 to disable, byte-identical)
+#   LOKI_UNCERTAINTY_ROUNDS       - Consecutive co-occurrence rounds before escalate (default: 2)
+#   LOKI_UNCERTAINTY_NOCHANGE_MIN - Proxy 1 threshold on consecutive_no_change (default: COUNCIL_STAGNATION_LIMIT - 1)
+#   LOKI_UNCERTAINTY_SPLIT_ROUNDS - Proxy 3 trailing split-round run length (default: 2)
 #
 # Usage:
 #   source autonomy/completion-council.sh
@@ -221,6 +225,7 @@ council_track_iteration() {
     _COUNCIL_TOTAL_DONE_SIGNALS="$COUNCIL_TOTAL_DONE_SIGNALS" \
     _COUNCIL_ITERATION="${ITERATION_COUNT:-0}" \
     _COUNCIL_FILES_CHANGED="$files_changed" \
+    _COUNCIL_DIFF_HASH="$combined_hash" \
     python3 -c "
 import json, os
 state_file = os.environ['_COUNCIL_STATE_FILE']
@@ -234,6 +239,7 @@ state['done_signals'] = int(os.environ['_COUNCIL_DONE_SIGNALS'])
 state['total_done_signals'] = int(os.environ['_COUNCIL_TOTAL_DONE_SIGNALS'])
 state['last_track_iteration'] = int(os.environ['_COUNCIL_ITERATION'])
 state['files_changed'] = int(os.environ['_COUNCIL_FILES_CHANGED'])
+state['last_diff_hash'] = os.environ['_COUNCIL_DIFF_HASH']
 with open(state_file, 'w') as f:
     json.dump(state, f, indent=2)
 " || log_warn "Failed to update council tracking state"
@@ -263,6 +269,282 @@ council_circuit_breaker_triggered() {
     return 1
 }
 
+#===============================================================================
+# Uncertainty-Gated Escalation - pure stuck-detection DECISION function
+#
+# Returns 0 = escalate now, 1 = do not escalate. Reads ONLY persisted state
+# (the council state.json for the three proxies, plus its own uncertainty.json
+# for the ring buffer + co-occurrence streak + debounce flag). Mutates only its
+# own uncertainty.json (atomic temp+mv). Fires NO notifications and touches NO
+# PAUSE file: the run.sh action site interprets the return code and performs the
+# side effects. This keeps the function sourceable and testable in isolation.
+#
+# Three proxies (all read from state, no live shell vars, no git calls):
+#   P1 (no-change)   : state.json consecutive_no_change >= NOCHANGE_MIN
+#                      (default COUNCIL_STAGNATION_LIMIT - 1, i.e. approaching
+#                      the circuit-breaker limit).
+#   P2 (oscillation) : current state.json last_diff_hash recurs at distance >= 2
+#                      in the ring buffer (A -> B -> A). Immediate repeat (A -> A)
+#                      is P1's territory and is excluded.
+#   P3 (council split): the trailing SPLIT_ROUNDS entries of state.json verdicts
+#                      are all result == "REJECTED" with approve >= 1.
+# Escalate iff >= 2 proxies are hot AND that has held for ROUNDS consecutive
+# rounds AND we have not already escalated this episode (debounce). Re-arm when
+# co-occurrence drops below 2 in any later round.
+#===============================================================================
+
+# Resolve the uncertainty.json path co-located with the council state root so a
+# sourced test (which sets COUNCIL_STATE_DIR to a throwaway dir) reads and writes
+# in that same throwaway dir, never the developer's real cwd. In production
+# COUNCIL_STATE_DIR is "${TARGET_DIR}/.loki/council", so its parent is the right
+# ".loki" and this lands at ".loki/state/uncertainty.json".
+_uncertainty_state_path() {
+    local base_dir="${COUNCIL_STATE_DIR:-${TARGET_DIR:-.}/.loki/council}"
+    local loki_root
+    loki_root="$(dirname "$base_dir")"
+    echo "$loki_root/state/uncertainty.json"
+}
+
+# Read uncertainty.json (or emit a default object if missing/corrupt) to stdout.
+_uncertainty_read_state() {
+    local file="$1"
+    _UNC_FILE="$file" python3 -c "
+import json, os
+f = os.environ['_UNC_FILE']
+default = {
+    'schema_version': '1.0.0',
+    'consecutive_co_occur': 0,
+    'escalated_episode': False,
+    'escalated_at_iteration': 0,
+    'diff_hash_ring': [],
+    'last_round_iteration': -1,
+    'last_proxies': {'p1': False, 'p2': False, 'p3': False},
+}
+try:
+    with open(f) as fh:
+        state = json.load(fh)
+    if not isinstance(state, dict):
+        state = {}
+except (json.JSONDecodeError, FileNotFoundError, OSError):
+    state = {}
+for k, v in default.items():
+    state.setdefault(k, v)
+print(json.dumps(state))
+" 2>/dev/null || echo '{}'
+}
+
+# Write a JSON string (read from _UNC_PAYLOAD) to uncertainty.json atomically
+# (temp + mv), mirroring evidence-block.json.
+_uncertainty_write_state() {
+    local file="$1"
+    local payload="$2"
+    local dir tmp
+    dir="$(dirname "$file")"
+    mkdir -p "$dir" 2>/dev/null || true
+    tmp="${file}.tmp.$$"
+    if _UNC_PAYLOAD="$payload" _UNC_TMP="$tmp" python3 -c "
+import json, os
+payload = os.environ['_UNC_PAYLOAD']
+tmp = os.environ['_UNC_TMP']
+state = json.loads(payload)
+with open(tmp, 'w') as fh:
+    json.dump(state, fh, indent=2)
+" 2>/dev/null; then
+        mv "$tmp" "$file" 2>/dev/null || { rm -f "$tmp" 2>/dev/null; return 1; }
+        return 0
+    fi
+    rm -f "$tmp" 2>/dev/null || true
+    return 1
+}
+
+uncertainty_should_escalate() {
+    # Knob first: opt-out is byte-identical to prior behavior. No read, no write,
+    # no state-file creation when disabled.
+    [ "${LOKI_UNCERTAINTY_ESCALATION:-1}" = "0" ] && return 1
+
+    # Tunable knobs (read inline; defaults documented in the env-var block).
+    local rounds_needed="${LOKI_UNCERTAINTY_ROUNDS:-2}"
+    local split_rounds="${LOKI_UNCERTAINTY_SPLIT_ROUNDS:-2}"
+    local nochange_min="${LOKI_UNCERTAINTY_NOCHANGE_MIN:-}"
+    if [ -z "$nochange_min" ]; then
+        nochange_min=$(( ${COUNCIL_STAGNATION_LIMIT:-5} - 1 ))
+        [ "$nochange_min" -lt 1 ] && nochange_min=1
+    fi
+    # Bounded constants.
+    local ring_size=6
+
+    # Resolve state file locations (council state root co-located).
+    local council_dir="${COUNCIL_STATE_DIR:-${TARGET_DIR:-.}/.loki/council}"
+    local state_json="$council_dir/state.json"
+    local unc_file
+    unc_file="$(_uncertainty_state_path)"
+    local iteration="${ITERATION_COUNT:-0}"
+
+    # Load prior uncertainty state.
+    local prior
+    prior="$(_uncertainty_read_state "$unc_file")"
+
+    # Compute the new state and decision entirely in python from persisted inputs.
+    # Echoes one line: "<rc> <new_json>" where rc is 0 (escalate) or 1 (no).
+    local result
+    result=$(_UNC_PRIOR="$prior" \
+             _UNC_STATE_JSON="$state_json" \
+             _UNC_ITERATION="$iteration" \
+             _UNC_ROUNDS="$rounds_needed" \
+             _UNC_SPLIT_ROUNDS="$split_rounds" \
+             _UNC_NOCHANGE_MIN="$nochange_min" \
+             _UNC_RING_SIZE="$ring_size" \
+             python3 -c "
+import json, os
+
+prior = json.loads(os.environ['_UNC_PRIOR'])
+iteration = int(os.environ['_UNC_ITERATION'])
+rounds_needed = int(os.environ['_UNC_ROUNDS'])
+split_rounds = int(os.environ['_UNC_SPLIT_ROUNDS'])
+nochange_min = int(os.environ['_UNC_NOCHANGE_MIN'])
+ring_size = int(os.environ['_UNC_RING_SIZE'])
+
+# Load council state.json (proxies). Missing/corrupt -> proxies cold.
+try:
+    with open(os.environ['_UNC_STATE_JSON']) as fh:
+        cstate = json.load(fh)
+    if not isinstance(cstate, dict):
+        cstate = {}
+except (json.JSONDecodeError, FileNotFoundError, OSError):
+    cstate = {}
+
+ring = prior.get('diff_hash_ring', [])
+if not isinstance(ring, list):
+    ring = []
+last_round = prior.get('last_round_iteration', -1)
+try:
+    last_round = int(last_round)
+except (TypeError, ValueError):
+    last_round = -1
+
+# Idempotency: a repeated call at the same iteration must not double-mutate.
+# Recompute proxies and re-emit the prior decision without pushing the ring or
+# advancing the streak again.
+same_round = (iteration == last_round)
+
+# --- Proxy 1: no-change approaching circuit breaker ---
+try:
+    no_change = int(cstate.get('consecutive_no_change', 0))
+except (TypeError, ValueError):
+    no_change = 0
+p1 = no_change >= nochange_min
+
+# --- Proxy 2: diff-hash recurrence at distance >= 2 (genuine oscillation) ---
+cur_hash = cstate.get('last_diff_hash', '')
+p2 = False
+if cur_hash:
+    # Genuine oscillation (A -> B -> A) requires TWO things:
+    #   1. cur_hash recurs in the ring excluding the most-recent entry
+    #      (distance >= 2; distance 1 immediate-repeat is P1's territory), AND
+    #   2. the most-recent ring entry (the previous round's hash) is DIFFERENT
+    #      from cur_hash, i.e. there is an intervening distinct hash.
+    # Without (2), pure stagnation (A, A, A, ...) fills the ring with the same
+    # hash and would falsely fire P2 from the SAME root condition as P1, letting
+    # a single condition (no-change) light two proxies and escalate alone. That
+    # contradicts the 2-of-3 independent-proxy safety guarantee. Requiring an
+    # intervening distinct hash keeps A,B,A hot and A,A,A cold.
+    prev_hash = ring[-1] if ring else ''
+    if prev_hash != cur_hash:
+        for h in ring[:-1]:
+            if h == cur_hash:
+                p2 = True
+                break
+
+# --- Proxy 3: persistent council split (trailing REJECTED with approve>=1) ---
+verdicts = cstate.get('verdicts', [])
+if not isinstance(verdicts, list):
+    verdicts = []
+split_run = 0
+for v in reversed(verdicts):
+    if not isinstance(v, dict):
+        break
+    try:
+        approve = int(v.get('approve', 0))
+    except (TypeError, ValueError):
+        approve = 0
+    if v.get('result') == 'REJECTED' and approve >= 1:
+        split_run += 1
+    else:
+        break
+p3 = split_run >= split_rounds
+
+hot_count = (1 if p1 else 0) + (1 if p2 else 0) + (1 if p3 else 0)
+co_occur = hot_count >= 2
+
+streak = prior.get('consecutive_co_occur', 0)
+try:
+    streak = int(streak)
+except (TypeError, ValueError):
+    streak = 0
+escalated_episode = bool(prior.get('escalated_episode', False))
+escalated_at = prior.get('escalated_at_iteration', 0)
+try:
+    escalated_at = int(escalated_at)
+except (TypeError, ValueError):
+    escalated_at = 0
+
+new_state = dict(prior)
+new_state['schema_version'] = prior.get('schema_version', '1.0.0')
+new_state['last_proxies'] = {'p1': p1, 'p2': p2, 'p3': p3}
+
+if same_round:
+    # No mutation of ring/streak; report no-escalate on the repeat call so we
+    # never fire twice for one round. Proxy snapshot is refreshed (harmless).
+    new_state['diff_hash_ring'] = ring
+    new_state['consecutive_co_occur'] = streak
+    new_state['escalated_episode'] = escalated_episode
+    new_state['escalated_at_iteration'] = escalated_at
+    new_state['last_round_iteration'] = last_round
+    rc = 1
+else:
+    # Advance the ring with this round's hash (bounded).
+    if cur_hash:
+        ring = ring + [cur_hash]
+        if len(ring) > ring_size:
+            ring = ring[-ring_size:]
+
+    if co_occur:
+        streak += 1
+    else:
+        # Re-arm on clear: a resolved episode may legitimately re-escalate later.
+        streak = 0
+        escalated_episode = False
+
+    rc = 1
+    if co_occur and streak >= rounds_needed and not escalated_episode:
+        rc = 0
+        escalated_episode = True
+        escalated_at = iteration
+
+    new_state['diff_hash_ring'] = ring
+    new_state['consecutive_co_occur'] = streak
+    new_state['escalated_episode'] = escalated_episode
+    new_state['escalated_at_iteration'] = escalated_at
+    new_state['last_round_iteration'] = iteration
+
+print(str(rc) + ' ' + json.dumps(new_state))
+" 2>/dev/null) || return 1
+
+    [ -z "$result" ] && return 1
+
+    local rc new_json
+    rc="${result%% *}"
+    new_json="${result#* }"
+
+    # Persist the new state atomically (failure to persist must not escalate).
+    _uncertainty_write_state "$unc_file" "$new_json" || return 1
+
+    case "$rc" in
+        0) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
 #===============================================================================
 # Council Voting - 3 independent reviewers check completion
 #===============================================================================

package/autonomy/config.example.yaml

@@ -80,6 +80,32 @@ completion:
   # Ignore ALL completion signals (runs forever)
   perpetual_mode: false
 
+  # Uncertainty-gated escalation (v7.19.2, default-on).
+  # When >=2 of 3 stuck-proxies (no-change counter, diff-hash oscillation,
+  # persistent council split) co-occur for `uncertainty.rounds` consecutive
+  # rounds, Loki escalates proactively via PAUSE + notification + handoff
+  # instead of silently burning iterations.
+  # IMPORTANT: when autonomy_mode is "perpetual" (the default), PAUSE is
+  # auto-cleared by the consumer so escalation degrades to notify-only; it
+  # does NOT halt the run. These are heuristics, not true metacognition.
+  #
+  # uncertainty:
+  #   # Master toggle. Set to 0 to disable (byte-identical when off).
+  #   escalation: 1
+  #
+  #   # Consecutive rounds where >=2 of 3 proxies must co-occur before
+  #   # escalating. Recommended range 2-3. Higher = less noise, later warning.
+  #   rounds: 2
+  #
+  #   # Proxy 1 threshold: consecutive_no_change must reach this value to mark
+  #   # the no-change proxy hot. Default is COUNCIL_STAGNATION_LIMIT - 1
+  #   # (one below the circuit-breaker limit). Leave unset to use the default.
+  #   # nochange_min: 4
+  #
+  #   # Proxy 3 threshold: trailing council verdicts that must be
+  #   # REJECTED-with-at-least-one-approver (split) to mark the split proxy hot.
+  #   split_rounds: 2
+
 #===============================================================================
 # Model & Routing Settings
 #===============================================================================

package/autonomy/run.sh

@@ -124,6 +124,26 @@
 #   LOKI_NOTIFICATIONS   - Enable desktop notifications (default: true)
 #   LOKI_NOTIFICATION_SOUND - Play sound with notifications (default: true)
 #
+# Uncertainty-Gated Escalation (v7.19.2, default-on):
+#   LOKI_UNCERTAINTY_ESCALATION  - Master on/off for proactive stuck-escalation (default: 1; set 0 to
+#                                  disable; byte-identical when off). Decision lives in
+#                                  completion-council.sh (uncertainty_should_escalate); action in run.sh.
+#                                  NOTE: AUTONOMY_MODE defaults to "perpetual"; in perpetual mode PAUSE
+#                                  is auto-cleared by check_human_intervention, so escalation degrades
+#                                  to notify-only (notification fires, run does NOT halt).
+#   LOKI_UNCERTAINTY_ROUNDS      - Consecutive rounds where >=2 of 3 proxies must co-occur before
+#                                  escalating (default: 2; recommended range 2-3). Debounces transient
+#                                  noise: a single hot proxy never escalates alone.
+#   LOKI_UNCERTAINTY_NOCHANGE_MIN - Proxy 1 threshold: consecutive_no_change value that marks p1 hot.
+#                                  (default: COUNCIL_STAGNATION_LIMIT - 1, i.e. one below the circuit-
+#                                  breaker limit so escalation fires before the breaker ends the run).
+#                                  Floored at 1 at runtime.
+#   LOKI_UNCERTAINTY_SPLIT_ROUNDS - Proxy 3 threshold: number of consecutive trailing council verdicts
+#                                  that must be REJECTED-with-approver (split) to mark p3 hot
+#                                  (default: 2). Between council votes p3 may be stale; it is always
+#                                  fresh when proxy 1 is hot because proxy 1 hot forces a circuit-
+#                                  breaker vote that refreshes verdicts.
+#
 # Human Intervention (Auto-Claude pattern):
 #   PAUSE file:          touch .loki/PAUSE - pauses after current session
 #   HUMAN_INPUT.md:      echo "instructions" > .loki/HUMAN_INPUT.md
@@ -286,6 +306,10 @@ parse_simple_yaml() {
     set_from_yaml "$file" "completion.council.check_interval" "LOKI_COUNCIL_CHECK_INTERVAL"
     set_from_yaml "$file" "completion.council.min_iterations" "LOKI_COUNCIL_MIN_ITERATIONS"
     set_from_yaml "$file" "completion.council.stagnation_limit" "LOKI_COUNCIL_STAGNATION_LIMIT"
+    set_from_yaml "$file" "completion.uncertainty.escalation" "LOKI_UNCERTAINTY_ESCALATION"
+    set_from_yaml "$file" "completion.uncertainty.rounds" "LOKI_UNCERTAINTY_ROUNDS"
+    set_from_yaml "$file" "completion.uncertainty.nochange_min" "LOKI_UNCERTAINTY_NOCHANGE_MIN"
+    set_from_yaml "$file" "completion.uncertainty.split_rounds" "LOKI_UNCERTAINTY_SPLIT_ROUNDS"
 
     # Model
     set_from_yaml "$file" "model.prompt_repetition" "LOKI_PROMPT_REPETITION"
@@ -428,6 +452,10 @@ parse_yaml_with_yq() {
         "completion.council.check_interval:LOKI_COUNCIL_CHECK_INTERVAL"
         "completion.council.min_iterations:LOKI_COUNCIL_MIN_ITERATIONS"
         "completion.council.stagnation_limit:LOKI_COUNCIL_STAGNATION_LIMIT"
+        "completion.uncertainty.escalation:LOKI_UNCERTAINTY_ESCALATION"
+        "completion.uncertainty.rounds:LOKI_UNCERTAINTY_ROUNDS"
+        "completion.uncertainty.nochange_min:LOKI_UNCERTAINTY_NOCHANGE_MIN"
+        "completion.uncertainty.split_rounds:LOKI_UNCERTAINTY_SPLIT_ROUNDS"
         "model.prompt_repetition:LOKI_PROMPT_REPETITION"
         "model.confidence_routing:LOKI_CONFIDENCE_ROUTING"
         "model.autonomy_mode:LOKI_AUTONOMY_MODE"
@@ -12390,6 +12418,33 @@ if __name__ == "__main__":
             council_track_iteration "$log_file"
         fi
 
+        # Uncertainty-gated escalation (v7.19.2, Slice B action).
+        # The decision lives in completion-council.sh:uncertainty_should_escalate
+        # (pure, debounced once-per-stuck-episode, knob-first on
+        # LOKI_UNCERTAINTY_ESCALATION). This block only ACTS when the function
+        # returns rc 0. The type guard keeps it a silent no-op if the decision
+        # function is not present (byte-identical when the feature is absent/off).
+        if type uncertainty_should_escalate &>/dev/null && uncertainty_should_escalate; then
+            log_error "[Uncertainty] Escalating to human: >=2 of 3 stuck-signals co-occurred for N rounds (no-change / oscillation / council-split). PAUSE written; handoff saved."
+            log_warn  "[Uncertainty] To opt out of proactive escalation: set LOKI_UNCERTAINTY_ESCALATION=0"
+            # Structured handoff doc before the bare PAUSE (mirrors GATE precedent).
+            write_structured_handoff "uncertainty_escalation"
+            notify_intervention_needed "Uncertainty escalation: >=2 of 3 stuck-signals co-occurred for N rounds"
+            # Marker file for dashboard / external consumers. Empty touch has no
+            # partial-write window, so atomic temp+mv is not required here.
+            mkdir -p "${TARGET_DIR:-.}/.loki/signals"
+            touch "${TARGET_DIR:-.}/.loki/signals/UNCERTAINTY_ESCALATION"
+            # PAUSE is consumed by check_human_intervention: it halts in
+            # non-perpetual mode; in perpetual mode it auto-clears + notifies.
+            # That degrade is free; we add no consumer logic here.
+            touch "${TARGET_DIR:-.}/.loki/PAUSE"
+            # Perpetual-mode honesty: detect with the SAME vars the existing PAUSE
+            # consumer uses (run.sh check_human_intervention), print-only.
+            if [ "$AUTONOMY_MODE" = "perpetual" ] || [ "$PERPETUAL_MODE" = "true" ]; then
+                log_warn "[Uncertainty] Perpetual mode: PAUSE will be auto-cleared; this is notify-only and will NOT halt the run."
+            fi
+        fi
+
         # Check for success - ONLY stop on explicit completion promise
         # There's never a "complete" product - always improvements, bugs, features
         if [ $exit_code -eq 0 ]; then

package/dashboard/__init__.py

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

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.19.1
+**Version:** v7.19.2
 
 ---
 

package/docs/UNCERTAINTY-ESCALATION-PLAN.md

@@ -0,0 +1,396 @@
+# Uncertainty-Gated Escalation (Loki Mode v7.19.2)
+
+Design only. No implementation code lands with this document. Every hook point
+below was read from live source; line numbers drift, so the verified anchors in
+section 1 are the contract a dev re-confirms before editing.
+
+## Goal
+
+When Loki is likely stuck or thrashing, escalate to the human PROACTIVELY via
+the EXISTING pause + notify + handoff machinery, instead of silently burning
+iterations until max-iterations. No new metacognition: reuse three proxy signals
+that already exist. Escalate only when at least two of the three co-occur for N
+consecutive rounds. Default-on, opt-out with LOKI_UNCERTAINTY_ESCALATION=0,
+byte-identical when off.
+
+## Architectural spine: split DECISION from ACTION
+
+This is the load-bearing decision and everything else falls out of it.
+
+- DECISION: a pure-ish function `uncertainty_should_escalate` lives in
+  `autonomy/completion-council.sh` next to the other `council_*` state helpers.
+  It reads ONLY persisted state (`state.json`, `convergence.log`, and its own
+  `.loki/state/uncertainty.json`), mutates only its own state file, and returns
+  rc 0 (escalate now) / rc 1 (do not). It fires NO notifications and touches NO
+  PAUSE file. This makes it sourceable and testable exactly like
+  `council_evidence_gate` (completion-council.sh:907): a test writes a fake
+  `state.json` into a throwaway dir and asserts the return code, with zero real
+  side effects on the developer's machine.
+- ACTION: the run.sh call site (new region right after
+  `council_track_iteration`, run.sh:12389-12391) interprets rc 0 and performs
+  the side effects: loud terminal line, `write_structured_handoff`,
+  `notify_intervention_needed`, write a `signals/UNCERTAINTY_ESCALATION` marker,
+  and `touch .loki/PAUSE`. It also emits the perpetual-mode honesty line.
+
+Consequence: the two code slices live in DIFFERENT files (decision in
+completion-council.sh, action in run.sh), so the dev fleet can build them in
+parallel without collision.
+
+---
+
+## 1. Verified hook points (read from live source)
+
+All paths relative to repo root `/Users/lokesh/git/loki-mode`.
+
+### Proxy 1 - circuit-breaker no-change counter
+- Var declared: `autonomy/completion-council.sh:70` (`COUNCIL_CONSECUTIVE_NO_CHANGE=0`).
+- Incremented: `completion-council.sh:178`; reset: `:180`. Driven by a combined
+  hash of `git diff --stat HEAD` + staged diff + last commit hash
+  (`:165-182`).
+- Limit knob: `COUNCIL_STAGNATION_LIMIT` (`:56`, default 5).
+- Persisted: written into `state.json` as `consecutive_no_change`
+  (`completion-council.sh:232` -> `:237` json.dump). THIS is what the decision
+  function reads (not the live shell var, which is out of scope in a sourced
+  test).
+- Updated every iteration via `council_track_iteration` (run.sh:12390).
+
+### Proxy 2 - file-churn oscillation / reverts
+- Existing data: `convergence.log` is appended at
+  `completion-council.sh:215` with line format
+  `timestamp|iteration|files_changed|consecutive_no_change|done_signals`.
+  CRITICAL: `files_changed` (`:208`) is a COUNT
+  (`git diff --name-only HEAD | wc -l`), NOT file identities. A count cannot
+  detect "same files back and forth."
+- The combined diff hash exists at `completion-council.sh:175`
+  (`combined_hash`), persisted only transiently in the shell var
+  `COUNCIL_LAST_DIFF_HASH` (`:73`, `:182`) - immediate-repeat only.
+- DECISION (see section 5 limits): proxy 2 is implemented as DIFF-HASH
+  RECURRENCE-AT-DISTANCE. We persist a small ring buffer (last
+  ~6 hashes) of `combined_hash` in `uncertainty.json`. Proxy 2 fires when the
+  current hash equals a hash seen 2+ rounds back (A -> B -> A pattern). The
+  immediate repeat (A -> A) is already proxy 1, so recurrence-at-distance is the
+  genuine oscillation/revert signal. This is a tiny, justified addition (one
+  bounded array in an existing JSON file), NOT heavy new tracking. The hash to
+  read is the same `combined_hash` proxy 1 already computes; the decision
+  function recomputes it cheaply from `git diff --stat HEAD` or, preferably,
+  `council_track_iteration` writes it into `state.json` (`last_diff_hash`) so the
+  decision function stays pure (no git calls). See slice A for which.
+
+### Proxy 3 - persistent council split
+- approve_count computed in `council_vote` (`completion-council.sh:270`,
+  tallied `:388`, anti-sycophancy adjust `:417`).
+- effective_threshold: `completion-council.sh:293`
+  (`(COUNCIL_SIZE * 2 + 2) / 3`, the ceiling(2/3) formula).
+- Persisted: each council round appends to `state['verdicts']`
+  (`completion-council.sh:449-455`) with keys `iteration`, `timestamp`,
+  `approve`, `reject`, `result` (`APPROVED`/`REJECTED`). NOTE: threshold is NOT
+  stored. That is fine: `result == "REJECTED"` already encodes
+  `approve < threshold`. A split round = `result == "REJECTED" AND approve >= 1`
+  (council could not converge: at least one approver, still short of threshold).
+  Do NOT go looking for a stored threshold; it is not there by design.
+- CADENCE: `verdicts` only appends when the council actually VOTES, which is
+  every `COUNCIL_CHECK_INTERVAL` OR when the circuit breaker forces a vote
+  (`council_should_stop`, completion-council.sh:2045-2051; circuit check
+  :2039-2043). So proxy 3 is STALE between votes. This is acceptable because in
+  the stuck regime we care about, proxy 1 going hot
+  (`consecutive_no_change >= COUNCIL_STAGNATION_LIMIT`) is exactly what TRIPS the
+  circuit breaker (`council_circuit_breaker_triggered`,
+  completion-council.sh:252) and forces a council vote, which refreshes proxy 3.
+  Verified: `council_should_stop` sets `should_check=true` when
+  `circuit_triggered=true` (:2047-2048). Document the between-votes staleness as
+  a known limit (section 5).
+
+### notify_intervention_needed
+- `autonomy/run.sh:2328`. Signature: `notify_intervention_needed "$reason"`;
+  thin wrapper over `send_notification "Intervention Needed" "$reason"
+  "critical"`.
+
+### PAUSE consume / clear path (perpetual-mode crux)
+- Consumer: `check_human_intervention` (run.sh:12701), PAUSE branch
+  `:12708`.
+- Perpetual auto-clear: `:12711-12730`. In perpetual mode PAUSE is
+  auto-cleared (`:12727 rm -f`) and `notify_intervention_needed` STILL fires
+  (`:12726`). Only `BUDGET_EXCEEDED` (`:12712`) is carved out from
+  auto-clear.
+- Non-perpetual: PAUSE triggers `handle_pause` (run.sh:12842) and waits
+  (`:12732-12742`).
+- Consumed once per loop turn from the main loop: `check_human_intervention`
+  is called at run.sh:11528, return-code switch `:11530-11533`
+  (1 = restart loop, 2 = stop).
+- IMPLICATION: escalation only WRITES PAUSE. The existing consumer halts (or, in
+  perpetual mode, auto-clears + notifies). Perpetual degrade is therefore FREE -
+  no new consumer logic. We detect perpetual at OUR site using the same vars
+  (`AUTONOMY_MODE` / `PERPETUAL_MODE`, run.sh:12711) only to print the honest
+  "notify-only; PAUSE will not halt this run" line.
+
+### write_structured_handoff
+- `autonomy/run.sh:8816`. Verified single live definition (the
+  "active definition is below" comment at :8811 refers to
+  `load_handoff_context`, not a second handoff def; grep shows one
+  `write_structured_handoff()`). Signature:
+  `write_structured_handoff "$reason"`; writes
+  `.loki/memory/handoffs/<ts>.json` + `.md`.
+
+### Loop point for the escalation check
+- Slot the ACTION immediately AFTER `council_track_iteration` in the main loop:
+  run.sh:12388-12391. At this point proxy 1 and proxy 2 are freshly written for
+  this iteration, and proxy 3 is fresh exactly when it matters (circuit-forced
+  vote). This is BEFORE the completion-promise / council checks
+  (run.sh:12408+), so escalation is evaluated every iteration.
+
+### Mirror precedent (action shape)
+- Gate-escalation block run.sh:12308-12318 is the precedent to clone: write a
+  `signals/` marker (`:12310`), call a handoff hook with its own opt-out
+  (`:12314`), then `touch .loki/PAUSE` (`:12317`). Our action mirrors this with
+  `write_structured_handoff` + `notify_intervention_needed` +
+  `signals/UNCERTAINTY_ESCALATION` + `touch .loki/PAUSE`.
+
+---
+
+## 2. Escalation decision function design
+
+### Inputs (all read from persisted state, no live shell vars)
+1. `p1` = proxy 1 hot: from `state.json.consecutive_no_change`. Hot when
+   `>= LOKI_UNCERTAINTY_NOCHANGE_MIN` (default = `COUNCIL_STAGNATION_LIMIT` - 1,
+   i.e. "approaching circuit-breaker"). Reading slightly below the breaker limit
+   lets us escalate BEFORE the breaker forces an end-state.
+2. `p2` = proxy 2 hot: diff-hash recurrence-at-distance. Hot when the current
+   `last_diff_hash` matches a hash at distance >= 2 in the ring buffer.
+3. `p3` = proxy 3 hot: persistent split. Read the last `K` entries of
+   `state.json.verdicts`; count consecutive trailing rounds where
+   `result == "REJECTED" AND approve >= 1`. Hot when that run length
+   `>= LOKI_UNCERTAINTY_SPLIT_ROUNDS` (default 2).
+
+### Co-occurrence + N-round debounce
+- Per round (= per iteration; "round" is defined as one main-loop iteration),
+  compute `hot_count = p1 + p2 + p3`.
+- `co_occur = (hot_count >= 2)`.
+- Maintain `consecutive_co_occur` in `uncertainty.json`:
+  - if `co_occur`: increment; else reset to 0.
+- Escalate (rc 0) when `consecutive_co_occur >= LOKI_UNCERTAINTY_ROUNDS`
+  (the N knob, default 2; recommended range 2-3) AND not already escalated this
+  episode (debounce flag, below).
+- A single noisy proxy can NEVER escalate alone (requires hot_count >= 2).
+
+### Debounce (escalate once per stuck-episode)
+- `uncertainty.json` carries `escalated_episode: true|false`.
+- On escalate, set `escalated_episode = true` and record
+  `escalated_at_iteration`.
+- Suppress re-fire while `escalated_episode == true`.
+- RE-ARM (reset `escalated_episode = false` and `consecutive_co_occur = 0`) when
+  `co_occur` becomes false in any later round (a proxy cleared => the episode is
+  considered resolved; a new stuck episode may legitimately re-escalate). State
+  the reset condition explicitly so a dev does not "helpfully" keep it latched.
+
+### State persistence
+- File: `.loki/state/uncertainty.json` (singular; the `uncertainty-*.json` glob
+  in the brief maps to this one file - keep it single to avoid an unbounded
+  directory). Schema:
+  ```json
+  {
+    "schema_version": "1.0.0",
+    "consecutive_co_occur": 0,
+    "escalated_episode": false,
+    "escalated_at_iteration": 0,
+    "diff_hash_ring": ["<h>", "<h>", "..."],
+    "last_round_iteration": 0,
+    "last_proxies": {"p1": false, "p2": false, "p3": false}
+  }
+  ```
+- Ring buffer bounded to 6 entries (constant). All writes atomic temp+mv,
+  mirroring evidence-block.json (`completion-council.sh:1059-1086`).
+
+### Knob-first byte-identical guard
+First line of `uncertainty_should_escalate`, BEFORE any read or write:
+```
+[ "${LOKI_UNCERTAINTY_ESCALATION:-1}" = "0" ] && return 1
+```
+(rc 1 = do-not-escalate; mirrors `council_evidence_gate`'s knob-first guard at
+completion-council.sh:909). When off: zero file reads, zero writes, zero state
+file creation => byte-identical.
+
+### Knobs summary (all opt-out / tunable, none required)
+- `LOKI_UNCERTAINTY_ESCALATION` (default 1) - master on/off.
+- `LOKI_UNCERTAINTY_ROUNDS` (default 2) - N consecutive co-occurrence rounds.
+- `LOKI_UNCERTAINTY_NOCHANGE_MIN` (default `COUNCIL_STAGNATION_LIMIT - 1`) - p1
+  threshold.
+- `LOKI_UNCERTAINTY_SPLIT_ROUNDS` (default 2) - p3 split run length.
+
+---
+
+## 3. Disjoint dev slices (parallel-safe)
+
+Binding constraints for EVERY slice: no version bumps (do not touch VERSION /
+CHANGELOG), no git commits, no emojis, no em-dashes or en-dashes (ASCII hyphen
+only), atomic temp+mv for all state writes, knob-first opt-out where the slice
+touches the hot loop.
+
+### Slice A - decision function + state schema (completion-council.sh)
+- Region: add `uncertainty_should_escalate` and a tiny
+  `_uncertainty_read_state` / `_uncertainty_write_state` pair near the other
+  `council_*` state helpers (after `council_circuit_breaker_triggered`,
+  i.e. around completion-council.sh:265, BEFORE `council_vote` at :270).
+- Also add ONE line inside `council_track_iteration` to persist
+  `state['last_diff_hash'] = combined_hash` (extend the python block at
+  completion-council.sh:224-238 by adding the env var + one assignment) so the
+  decision function reads the hash from state.json and stays pure (no git in the
+  decision path). This is the only edit inside an existing function; keep it to a
+  single key add to minimize collision with run.sh slice.
+- Owns: `.loki/state/uncertainty.json` schema, ring buffer, co-occurrence +
+  debounce logic, all four knobs' defaults.
+- File-region disjoint from slice B (different file).
+
+### Slice B - action + wiring (run.sh)
+- Region: new block right after `council_track_iteration` call
+  (run.sh:12389-12391).
+- Logic:
+  ```
+  if type uncertainty_should_escalate >/dev/null 2>&1 && uncertainty_should_escalate; then
+      # loud line (section 6), write_structured_handoff "uncertainty_escalation",
+      # notify_intervention_needed, signals/UNCERTAINTY_ESCALATION marker,
+      # touch .loki/PAUSE, perpetual honesty line.
+  fi
+  ```
+- Clone the GATE_ESCALATION shape (run.sh:12308-12318) for marker + handoff +
+  touch ordering.
+- Perpetual detection: read `AUTONOMY_MODE` / `PERPETUAL_MODE`
+  (same as run.sh:12711) ONLY to print the honest notify-only line.
+- File-region disjoint from slices A, C, D.
+
+### Slice C - tests (tests/test-uncertainty-escalation.sh)
+- New file. Sources the real `uncertainty_should_escalate` from
+  completion-council.sh, stubs `log_*`, runs per-case throwaway dirs. Models
+  tests/test-evidence-gate.sh exactly. Asserts decision-only (no real notify /
+  no real PAUSE because it calls the DECISION function, not the run.sh action).
+- File-region disjoint (new file).
+
+### Slice D - docs + knob registration
+- Register the four knobs in the config-comment block (the env-var doc region
+  around run.sh:91-128 and the yaml mapping near :282/:424) and
+  `autonomy/config.example.yaml`. Add a short section to the user-facing docs.
+- Keep edits to comment / config blocks; do not touch the hot loop. If this
+  collides with slice B's run.sh edits, sequence D after B (the only soft
+  dependency). Otherwise fully disjoint.
+
+Recommended parallelism: A, C, D in parallel; B after A's function signature is
+agreed (C can mock the signature meanwhile). 4 slices, 3 files + 1 new test +
+docs.
+
+---
+
+## 4. Test plan (model: tests/test-evidence-gate.sh)
+
+Harness: source the real completion-council.sh with `log_*` stubbed; call
+`uncertainty_should_escalate` inside per-case `mktemp -d` dirs, each writing its
+own `.loki/state/uncertainty.json` + `.loki/council/state.json` +
+`.loki/council/convergence.log`. Assert BOTH rc and the mutated
+`uncertainty.json` side effects. Loud SKIP (exit 0) if the function is not yet
+defined (mirrors evidence-gate's absent-impl banner). Each case sets
+`COUNCIL_STATE_DIR` and `ITERATION_COUNT` explicitly.
+
+Cases:
+1. PROXY READ - p1 only hot: `consecutive_no_change` >= min, hash unique,
+   verdicts approved. Assert `last_proxies.p1 == true`, others false, rc 1
+   (NO escalate on 1 proxy). Proves proxy 1 is read.
+2. PROXY READ - p2 only hot: write a recurrence-at-distance hash ring
+   (A,B,A), unique p1/p3. Assert `p2 == true`, rc 1. Proves proxy 2 is read
+   from the ring, and that immediate-repeat (A,A) does NOT count as p2.
+3. PROXY READ - p3 only hot: verdicts trailing K = REJECTED with approve>=1 for
+   SPLIT_ROUNDS rounds. Assert `p3 == true`, rc 1. Proves proxy 3 reads
+   `result`/`approve` (and does NOT require a stored threshold).
+4. CO-OCCURRENCE x N escalates: set p1 + p3 hot for N consecutive calls
+   (loop the function N times, advancing iteration). Assert rc 0 on the Nth
+   call, `escalated_episode == true`. Proves >=2-for-N escalates.
+5. 1-PROXY-NEVER: keep only one proxy hot for many rounds. Assert rc 1 every
+   round, `escalated_episode == false`. Proves a single noisy proxy cannot
+   escalate.
+6. DEBOUNCE (no re-fire): after case-4 escalation, call again with the SAME hot
+   proxies. Assert rc 1 (suppressed) while `escalated_episode == true`. Proves
+   escalate-once-per-episode.
+7. RE-ARM: after escalation, feed one round with co_occur false (clear a proxy),
+   assert `escalated_episode == false` + `consecutive_co_occur == 0`; then feed
+   N hot rounds again, assert rc 0. Proves reset-on-clear and re-escalation of a
+   new episode.
+8. OPT-OUT BYTE-IDENTICAL: `LOKI_UNCERTAINTY_ESCALATION=0`. Assert rc 1 AND that
+   `.loki/state/uncertainty.json` is NOT created / NOT modified (snapshot the
+   dir before/after; mtime + existence). Proves byte-identical when off.
+9. PERPETUAL DEGRADE-TO-NOTIFY: this is a run.sh ACTION behavior, so test it as a
+   thin integration shim: stub `notify_intervention_needed`, `handle_pause`,
+   `handle_dashboard_crash` to record calls; set `AUTONOMY_MODE=perpetual`;
+   `touch .loki/PAUSE`; call the real `check_human_intervention`
+   (run.sh:12701). Assert PAUSE is auto-cleared AND notify was called (proves
+   the degrade path is the EXISTING consumer at run.sh:12725-12727, so escalation
+   degrades to notify-only under perpetual). This case sources run.sh's
+   `check_human_intervention` with its deps stubbed, or asserts via a focused
+   harness; if sourcing run.sh wholesale is impractical, assert the contract by
+   reading the consumer branch and documenting it as a code-path test.
+
+All cases: throwaway git repos isolated via `GIT_CONFIG_GLOBAL=/dev/null`
+(mirror test-evidence-gate.sh:107-115). Skip-not-fail on missing git/python3.
+
+---
+
+## 5. Honest limits
+
+- PERPETUAL-MODE = NOTIFY-ONLY. If Loki runs in perpetual / auto-continue mode,
+  the existing consumer (`check_human_intervention`, run.sh:12725-12727)
+  auto-clears PAUSE and continues. Escalation therefore DEGRADES to a
+  notification (notify still fires) plus a handoff doc; it does NOT halt the run.
+  We detect this at the action site and print it honestly. We deliberately do
+  NOT add a no-auto-clear carve-out for our marker (the BUDGET_EXCEEDED carve-out
+  at run.sh:12712 shows it is technically possible) because that is scope creep
+  and would break "byte-identical when off." Out of scope for v7.19.2; candidate
+  follow-up.
+- PROXY 2 IS COUNT-BLIND BY ORIGIN. `convergence.log` stores `files_changed` as
+  a count (completion-council.sh:208), not identities, so it cannot by itself see
+  "same files back and forth." We approximate oscillation with diff-hash
+  recurrence-at-distance, which catches A -> B -> A state cycling but CANNOT
+  distinguish a genuine revert from a coincidental return to an identical tree
+  state, and will MISS oscillation that changes content each pass (hash differs
+  every round). It is a heuristic, not a true revert detector.
+- PROXY 3 STALENESS BETWEEN VOTES. The verdicts array only updates on actual
+  council votes (every `COUNCIL_CHECK_INTERVAL` or circuit-forced). Sampled every
+  iteration, p3 can be stale between votes. We rely on the circuit-breaker
+  coupling (proxy 1 hot forces a vote, refreshing p3) so p3 is fresh exactly in
+  the regime we escalate on; outside that regime p3 may lag by up to
+  `COUNCIL_CHECK_INTERVAL` iterations.
+- PROXIES FALSE-FIRE AND MISS. All three are heuristics. A legitimately hard
+  refactor that produces no net diff for several rounds while the council
+  remains split can false-fire; a fast-thrashing failure that keeps changing
+  different files with shifting hashes can be missed. Requiring >=2 co-occurring
+  for N rounds reduces, but does not eliminate, false fires. The cost of a false
+  fire is bounded: one notification + one handoff + one PAUSE (auto-cleared in
+  perpetual), opt-out at the site.
+- THESE ARE PROXIES, NOT TRUE METACOGNITION. The system does not know it is
+  stuck; it infers stuckness from three correlated symptoms of stuckness. There
+  is no model of confidence, no self-estimate of progress. This is intentional
+  (no new metacognition) and is the honest ceiling on what this feature can
+  claim.
+
+---
+
+## 6. Rails (the v7.19.1 evidence-gate rails, mirrored)
+
+A default-on hook in the hot loop must be bounded, loud, and self-rescuing.
+
+- BOUNDED: the decision function does O(1) work - reads two small JSON files,
+  scans the last K verdicts and a 6-entry ring. No git subprocess in the decision
+  path (hash comes from state.json via slice A's one-line add). No network. No
+  unbounded loop. Cannot hang. The action runs at most ONCE per stuck episode
+  (debounce), not every iteration.
+- LOUD TERMINAL LINE at the escalation site (run.sh, slice B):
+  ```
+  log_error "[Uncertainty] Escalating to human: >=2 of 3 stuck-signals co-occurred for N rounds (no-change / oscillation / council-split). PAUSE written; handoff saved."
+  log_warn  "[Uncertainty] To opt out of proactive escalation: set LOKI_UNCERTAINTY_ESCALATION=0"
+  ```
+  And, only when perpetual, the honesty line:
+  ```
+  log_warn  "[Uncertainty] Perpetual mode: PAUSE will be auto-cleared; this is notify-only and will NOT halt the run."
+  ```
+- OPT-OUT NAMED AT THE SITE: the opt-out env var is printed on the line above,
+  right where escalation happens, so a terminal user with no dashboard can
+  self-rescue in one step (mirrors completion-council.sh:1055).
+- KNOB-FIRST: `LOKI_UNCERTAINTY_ESCALATION=0` short-circuits the decision
+  function before any read/write (section 2), and `type ... >/dev/null` guards
+  the run.sh call so an unbuilt function is a silent no-op. Byte-identical when
+  off, proven by test case 8.

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var f8=Object.defineProperty;var u8=($)=>$;function c8($,Q){this[$]=u8.bind(null,Q)}var g=($,Q)=>{for(var K in Q)f8($,K,{get:Q[K],enumerable:!0,configurable:!0,set:c8.bind(Q,K)})};var k=($,Q)=>()=>($&&(Q=$($=0)),Q);var X1=import.meta.require;var F$={};g(F$,{lokiDir:()=>P,homeLokiDir:()=>o1,findRepoRootForVersion:()=>d1,REPO_ROOT:()=>f});import{resolve as n,dirname as l1}from"path";import{fileURLToPath as p8}from"url";import{existsSync as L1}from"fs";import{homedir as l8}from"os";function d8(){let $=j$;for(let Q=0;Q<6;Q++){if(L1(n($,"VERSION"))&&L1(n($,"autonomy/run.sh")))return $;let K=l1($);if(K===$)break;$=K}return n(j$,"..","..","..")}function d1($){let Q=$;for(let K=0;K<6;K++){if(L1(n(Q,"VERSION"))&&L1(n(Q,"autonomy/run.sh")))return Q;let Z=l1(Q);if(Z===Q)break;Q=Z}return n($,"..","..","..")}function P(){return process.env.LOKI_DIR??n(process.cwd(),".loki")}function o1(){return n(l8(),".loki")}var j$,f;var y=k(()=>{j$=l1(p8(import.meta.url));f=d8()});import{readFileSync as o8}from"fs";import{resolve as n8,dirname as a8}from"path";import{fileURLToPath as s8}from"url";function k1(){if($1!==null)return $1;let $="7.19.1";if(typeof $==="string"&&$.length>0)return $1=$,$1;try{let Q=a8(s8(import.meta.url)),K=d1(Q);$1=o8(n8(K,"VERSION"),"utf-8").trim()}catch{$1="unknown"}return $1}var $1=null;var n1=k(()=>{y()});var E$={};g(E$,{runOrThrow:()=>t8,run:()=>j,commandVersion:()=>i8,commandExists:()=>v,ShellError:()=>a1});async function j($,Q={}){let K=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),Z,z;if(Q.timeoutMs&&Q.timeoutMs>0)Z=setTimeout(()=>{try{K.kill("SIGTERM")}catch{}z=setTimeout(()=>{try{K.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[H,X,q]=await Promise.all([new Response(K.stdout).text(),new Response(K.stderr).text(),K.exited]);return{stdout:H,stderr:X,exitCode:q}}finally{if(Z)clearTimeout(Z);if(z)clearTimeout(z)}}async function t8($,Q={}){let K=await j($,Q);if(K.exitCode!==0)throw new a1(`command failed (${K.exitCode}): ${$.join(" ")}`,K.exitCode,K.stdout,K.stderr);return K}async function v($){let Q=r8($),K=await j(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(K.exitCode===0)return K.stdout.trim()||null;return null}function r8($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function i8($,Q="--version"){if(!await v($))return null;let Z=await j([$,Q],{timeoutMs:5000});if(Z.exitCode!==0)return null;return((Z.stdout||Z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var a1;var d=k(()=>{a1=class a1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,K,Z){super($);this.message=$;this.exitCode=Q;this.stdout=K;this.stderr=Z;this.name="ShellError"}}});function a($){return e8?"":$}var e8,T,N,w,ZK,_,R,h,J;var c=k(()=>{e8=(process.env.NO_COLOR??"").length>0;T=a("\x1B[0;31m"),N=a("\x1B[0;32m"),w=a("\x1B[1;33m"),ZK=a("\x1B[0;34m"),_=a("\x1B[0;36m"),R=a("\x1B[1m"),h=a("\x1B[2m"),J=a("\x1B[0m")});import{existsSync as U7}from"fs";async function Q1(){if(B1!==void 0)return B1;let $="/opt/homebrew/bin/python3.12";if(U7($))return B1=$,$;let Q=await v("python3.12");if(Q)return B1=Q,Q;let K=await v("python3");return B1=K,K}async function K1($,Q={}){let K=await Q1();if(!K)return{stdout:"",stderr:"python3 not found",exitCode:127};return j([K,"-c",$],Q)}var B1;var H1=k(()=>{d()});var d$={};g(d$,{runStatus:()=>N7});import{existsSync as b,readFileSync as q1,readdirSync as v$,statSync as f$}from"fs";import{resolve as D,basename as P7}from"path";import{homedir as L7}from"os";async function j7(){if(await v("jq"))return!0;return process.stdout.write(`${T}Error: jq is required but not installed.${J}
+var f8=Object.defineProperty;var u8=($)=>$;function c8($,Q){this[$]=u8.bind(null,Q)}var g=($,Q)=>{for(var K in Q)f8($,K,{get:Q[K],enumerable:!0,configurable:!0,set:c8.bind(Q,K)})};var k=($,Q)=>()=>($&&(Q=$($=0)),Q);var X1=import.meta.require;var F$={};g(F$,{lokiDir:()=>P,homeLokiDir:()=>o1,findRepoRootForVersion:()=>d1,REPO_ROOT:()=>f});import{resolve as n,dirname as l1}from"path";import{fileURLToPath as p8}from"url";import{existsSync as L1}from"fs";import{homedir as l8}from"os";function d8(){let $=j$;for(let Q=0;Q<6;Q++){if(L1(n($,"VERSION"))&&L1(n($,"autonomy/run.sh")))return $;let K=l1($);if(K===$)break;$=K}return n(j$,"..","..","..")}function d1($){let Q=$;for(let K=0;K<6;K++){if(L1(n(Q,"VERSION"))&&L1(n(Q,"autonomy/run.sh")))return Q;let Z=l1(Q);if(Z===Q)break;Q=Z}return n($,"..","..","..")}function P(){return process.env.LOKI_DIR??n(process.cwd(),".loki")}function o1(){return n(l8(),".loki")}var j$,f;var y=k(()=>{j$=l1(p8(import.meta.url));f=d8()});import{readFileSync as o8}from"fs";import{resolve as n8,dirname as a8}from"path";import{fileURLToPath as s8}from"url";function k1(){if($1!==null)return $1;let $="7.19.2";if(typeof $==="string"&&$.length>0)return $1=$,$1;try{let Q=a8(s8(import.meta.url)),K=d1(Q);$1=o8(n8(K,"VERSION"),"utf-8").trim()}catch{$1="unknown"}return $1}var $1=null;var n1=k(()=>{y()});var E$={};g(E$,{runOrThrow:()=>t8,run:()=>j,commandVersion:()=>i8,commandExists:()=>v,ShellError:()=>a1});async function j($,Q={}){let K=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),Z,z;if(Q.timeoutMs&&Q.timeoutMs>0)Z=setTimeout(()=>{try{K.kill("SIGTERM")}catch{}z=setTimeout(()=>{try{K.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[H,X,q]=await Promise.all([new Response(K.stdout).text(),new Response(K.stderr).text(),K.exited]);return{stdout:H,stderr:X,exitCode:q}}finally{if(Z)clearTimeout(Z);if(z)clearTimeout(z)}}async function t8($,Q={}){let K=await j($,Q);if(K.exitCode!==0)throw new a1(`command failed (${K.exitCode}): ${$.join(" ")}`,K.exitCode,K.stdout,K.stderr);return K}async function v($){let Q=r8($),K=await j(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(K.exitCode===0)return K.stdout.trim()||null;return null}function r8($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function i8($,Q="--version"){if(!await v($))return null;let Z=await j([$,Q],{timeoutMs:5000});if(Z.exitCode!==0)return null;return((Z.stdout||Z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var a1;var d=k(()=>{a1=class a1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,K,Z){super($);this.message=$;this.exitCode=Q;this.stdout=K;this.stderr=Z;this.name="ShellError"}}});function a($){return e8?"":$}var e8,T,N,w,ZK,_,R,h,J;var c=k(()=>{e8=(process.env.NO_COLOR??"").length>0;T=a("\x1B[0;31m"),N=a("\x1B[0;32m"),w=a("\x1B[1;33m"),ZK=a("\x1B[0;34m"),_=a("\x1B[0;36m"),R=a("\x1B[1m"),h=a("\x1B[2m"),J=a("\x1B[0m")});import{existsSync as U7}from"fs";async function Q1(){if(B1!==void 0)return B1;let $="/opt/homebrew/bin/python3.12";if(U7($))return B1=$,$;let Q=await v("python3.12");if(Q)return B1=Q,Q;let K=await v("python3");return B1=K,K}async function K1($,Q={}){let K=await Q1();if(!K)return{stdout:"",stderr:"python3 not found",exitCode:127};return j([K,"-c",$],Q)}var B1;var H1=k(()=>{d()});var d$={};g(d$,{runStatus:()=>N7});import{existsSync as b,readFileSync as q1,readdirSync as v$,statSync as f$}from"fs";import{resolve as D,basename as P7}from"path";import{homedir as L7}from"os";async function j7(){if(await v("jq"))return!0;return process.stdout.write(`${T}Error: jq is required but not installed.${J}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -787,4 +787,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${Q}
 `),process.stderr.write(v8),2}}g$();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var p3=await c3(Bun.argv.slice(2));process.exit(p3);
 
-//# debugId=C5A2181B4CB7536864756E2164756E21
+//# debugId=A2F8B15FD75062F064756E2164756E21

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '7.19.1'
+__version__ = '7.19.2'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "7.19.1",
+  "version": "7.19.2",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 11 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/skills/quality-gates.md

@@ -202,6 +202,91 @@ crash via the primitive's `finally` cleanup.
 
 ---
 
+## Uncertainty-gated escalation (v7.19.2, default-on)
+
+When Loki is likely stuck or thrashing, it escalates proactively to the human
+via the existing PAUSE + notification + handoff machinery, rather than silently
+burning iterations until max-iterations. No new metacognition: the system
+reuses three proxy signals that already exist and escalates only when at least
+two of the three co-occur for N consecutive rounds.
+
+### Trigger condition
+
+Three proxy signals are evaluated each iteration:
+
+- **Proxy 1 (no-change counter):** `consecutive_no_change` in council state.json
+  reaches `LOKI_UNCERTAINTY_NOCHANGE_MIN` (default: `COUNCIL_STAGNATION_LIMIT - 1`,
+  i.e. one below the circuit-breaker limit so escalation fires before the
+  breaker ends the run).
+- **Proxy 2 (diff-hash oscillation):** the current iteration's combined diff
+  hash matches a hash seen 2+ rounds back in a bounded ring buffer (A -> B -> A
+  pattern). Detects oscillation/revert cycling; does not fire on the trivial
+  immediate-repeat case which proxy 1 already covers.
+- **Proxy 3 (persistent council split):** the last `LOKI_UNCERTAINTY_SPLIT_ROUNDS`
+  consecutive council verdicts are all REJECTED-with-at-least-one-approver
+  (split verdict). Stale between council votes; fresh exactly when proxy 1 is
+  hot, because proxy 1 hot forces a circuit-breaker vote that refreshes verdicts.
+
+Escalation fires when `hot_count >= 2` (at least two proxies hot simultaneously)
+for `LOKI_UNCERTAINTY_ROUNDS` consecutive rounds AND the episode has not already
+been escalated (one escalation per stuck-episode, with re-arm when co-occurrence
+clears).
+
+### Action
+
+When the trigger condition is met, the run.sh action block:
+
+1. Prints a loud terminal line with the opt-out env var.
+2. Calls `write_structured_handoff "uncertainty_escalation"` (saves
+   `.loki/memory/handoffs/<ts>.json` and `.md`).
+3. Calls `notify_intervention_needed` with a structured reason string.
+4. Writes a `.loki/signals/UNCERTAINTY_ESCALATION` marker file.
+5. Touches `.loki/PAUSE`.
+
+### Knobs
+
+```bash
+LOKI_UNCERTAINTY_ESCALATION=0    # Disable entirely. Byte-identical when off:
+                                 # zero reads, zero writes, no state file.
+                                 # Default: 1 (enabled). Toggle value is 0/1,
+                                 # not false/true.
+LOKI_UNCERTAINTY_ROUNDS=2        # Consecutive co-occurrence rounds required.
+                                 # Recommended range 2-3. Default: 2.
+LOKI_UNCERTAINTY_NOCHANGE_MIN=N  # Proxy 1 threshold. Unset = auto-computed as
+                                 # COUNCIL_STAGNATION_LIMIT - 1 (floored at 1).
+LOKI_UNCERTAINTY_SPLIT_ROUNDS=2  # Proxy 3 trailing split-round run length.
+                                 # Default: 2.
+```
+
+Configurable via `config.yaml` under `completion.uncertainty.*` (see
+`autonomy/config.example.yaml`).
+
+### Honest limits
+
+- **Perpetual-mode = notify-only by default.** `AUTONOMY_MODE` defaults to
+  `perpetual`. In perpetual mode the existing consumer (`check_human_intervention`)
+  auto-clears PAUSE and continues. Escalation therefore degrades to a notification
+  plus a handoff document; it does NOT halt the run. The terminal prints an explicit
+  warning at the escalation site: "Perpetual mode: PAUSE will be auto-cleared; this
+  is notify-only and will NOT halt the run."
+- **Proxy 2 is count-blind by origin.** It approximates oscillation with
+  diff-hash recurrence-at-distance; it cannot distinguish a genuine revert from
+  a coincidental identical tree state, and misses oscillation where the hash
+  differs every round.
+- **Proxy 3 is stale between council votes.** Verdicts are only appended when the
+  council actually votes (every `COUNCIL_CHECK_INTERVAL` or circuit-forced). In
+  practice p3 is always fresh in the regime that matters (proxy 1 hot forces a
+  vote), but it may lag by up to `COUNCIL_CHECK_INTERVAL` iterations otherwise.
+- **These are heuristics, not true metacognition.** The system does not know it
+  is stuck; it infers stuckness from three correlated symptoms. A legitimately
+  hard refactor that produces no net diff for several rounds while the council
+  remains split can false-fire. Requiring >=2 co-occurring for N rounds reduces
+  but does not eliminate false fires. The cost of a false fire is bounded: one
+  notification + one handoff + one PAUSE (auto-cleared in perpetual), opt-out
+  at the site.
+
+---
+
 ## Guardrails Execution Modes
 
 - **Blocking**: Guardrail completes before agent starts (use for expensive operations)