loki-mode 7.19.1 → 7.19.3

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.3";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=DB7AECDBE28F921664756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "7.19.1",
+  "version": "7.19.3",
   "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)