loki-mode 7.7.20 → 7.7.22

package/SKILL.md

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

package/VERSION

@@ -1 +1 @@
-7.7.20
+7.7.22

package/autonomy/loki

@@ -15054,6 +15054,7 @@ except Exception as e:
             echo ""
             echo "  loki memory ingest --from-claude-transcript <path>  # v7.7.18"
             echo "  loki memory ingest --from-stdin                     # v7.7.18"
+            echo "  loki memory replay <episode-id> [--json]            # v7.7.22"
             echo "  loki memory crossproject --for 'build api'          # v7.7.20"
             echo "  loki memory graph --export graph.json               # v7.7.20"
             echo "  loki memory graph rebuild                           # v7.7.20"
@@ -15138,6 +15139,41 @@ print(json.dumps({'episode_path': path}))
             fi
             ;;
 
+        replay)
+            # v7.7.22 wow feature: READ-ONLY deterministic session replay.
+            # Renders a past episode's action timeline + current state of
+            # touched files. Does NOT re-execute (LLM tool_uses are
+            # non-deterministic + re-running edits could clobber work;
+            # --apply deferred to a future release).
+            # Usage: loki memory replay <episode-id> [--json]
+            shift  # drop "replay"
+            local _replay_id=""
+            local _replay_json="false"
+            while [ $# -gt 0 ]; do
+                case "$1" in
+                    --json) _replay_json="true"; shift ;;
+                    -h|--help) echo "Usage: loki memory replay <episode-id> [--json]"; return 0 ;;
+                    *) [ -z "$_replay_id" ] && _replay_id="$1"; shift ;;
+                esac
+            done
+            if [ -z "$_replay_id" ]; then
+                echo -e "${RED}Usage: loki memory replay <episode-id> [--json]${NC}"
+                exit 1
+            fi
+            local _replay_mem
+            _replay_mem="$(pwd)/.loki/memory"
+            PYTHONPATH="${SKILL_DIR:-$(pwd)}" _LOKI_REPLAY_JSON="$_replay_json" python3 -c "
+import sys, os, json
+from memory.replay import replay_episode, render_markdown
+report = replay_episode(sys.argv[1], sys.argv[2])
+if os.environ.get('_LOKI_REPLAY_JSON') == 'true':
+    print(json.dumps(report, indent=2, default=str))
+else:
+    print(render_markdown(report))
+sys.exit(0 if report.get('found') else 1)
+" "$_replay_id" "$_replay_mem"
+            ;;
+
         crossproject)
             # v7.7.20: surface cross-project knowledge-graph patterns
             # (wakes the previously-dead memory/knowledge_graph.py).

package/dashboard/__init__.py

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

package/dashboard/server.py

@@ -2638,16 +2638,115 @@ async def get_skill(skill_id: str):
     raise HTTPException(status_code=404, detail="Skill not found")
 
 
-@app.get("/api/memory/economics")
+@app.get("/api/memory/economics", dependencies=[Depends(auth.require_scope("read"))])
 async def get_token_economics():
-    """Get token usage economics."""
-    econ_file = _get_loki_dir() / "memory" / "token_economics.json"
+    """Get token usage economics (v7.7.21: normalized + hit_rate + top_patterns).
+
+    Excellence bar 5: per-retrieval cost + hit rate + top patterns visible.
+    Reads token_economics.json (written by memory.token_economics.save())
+    which has shape {session_id, metrics:{discovery_tokens, read_tokens,
+    cache_hits, cache_misses, ...}, ratio, savings_percent}. Computes a
+    cache hit_rate + surfaces the most-accessed episodes/patterns. The
+    pre-v7.7.21 endpoint returned camelCase keys that did not match the
+    snake_case file; the `raw` field preserves the original document for
+    backward compat while the top-level fields are normalized.
+    """
+    loki_dir = _get_loki_dir()
+    econ_file = loki_dir / "memory" / "token_economics.json"
+    raw = {}
     if econ_file.exists():
         try:
-            return json.loads(econ_file.read_text())
+            raw = json.loads(econ_file.read_text())
         except Exception:
-            pass
-    return {"discoveryTokens": 0, "readTokens": 0, "savingsPercent": 0}
+            raw = {}
+
+    metrics = raw.get("metrics", {}) if isinstance(raw, dict) else {}
+    cache_hits = int(metrics.get("cache_hits", 0) or 0)
+    cache_misses = int(metrics.get("cache_misses", 0) or 0)
+    cache_total = cache_hits + cache_misses
+    hit_rate = round(cache_hits / cache_total, 4) if cache_total > 0 else 0.0
+    discovery_tokens = int(metrics.get("discovery_tokens", 0) or 0)
+    read_tokens = int(metrics.get("read_tokens", 0) or 0)
+
+    # Top-accessed memories: scan episodic + semantic, rank by access_count
+    # then importance.
+    # v7.7.21 council fix (Opus 1 + Opus 2):
+    #   - os.walk(followlinks=False) instead of recursive glob: does NOT
+    #     descend symlinked dirs (prevents traversal/exfil + DoS-amplify
+    #     via a symlink to a huge tree).
+    #   - realpath containment: every candidate file must resolve to a
+    #     path under mem_root (mirrors the sibling get_skill endpoint).
+    #   - hard cap on files SCANNED (not just surfaced): stop after
+    #     MAX_SCAN files per subdir so a large store cannot make this
+    #     request unboundedly slow even with the 30s auto-refresh.
+    top_patterns = []
+    try:
+        import os as _os
+        mem_root = (loki_dir / "memory").resolve()
+        MAX_SCAN = 300
+        candidates = []
+        for sub in ("episodic", "semantic"):
+            sub_root = mem_root / sub
+            if not sub_root.is_dir():
+                continue
+            scanned = 0
+            stop = False
+            for dirpath, dirnames, filenames in _os.walk(str(sub_root), followlinks=False):
+                if stop:
+                    break
+                for fn in filenames:
+                    if not fn.endswith(".json"):
+                        continue
+                    fp = _os.path.join(dirpath, fn)
+                    # Containment: resolved path must stay under mem_root.
+                    try:
+                        rp = _os.path.realpath(fp)
+                        if _os.path.commonpath([rp, str(mem_root)]) != str(mem_root):
+                            continue
+                    except (OSError, ValueError):
+                        continue
+                    try:
+                        with open(fp) as fh:
+                            d = json.load(fh)
+                        candidates.append({
+                            "id": d.get("id", ""),
+                            "kind": sub,
+                            "access_count": int(d.get("access_count", 0) or 0),
+                            "importance": float(d.get("importance", 0.0) or 0.0),
+                            "summary": str(
+                                d.get("summary")
+                                or d.get("pattern")
+                                or d.get("context", {}).get("goal", "")
+                            )[:160],
+                        })
+                    except Exception:
+                        continue
+                    scanned += 1
+                    if scanned >= MAX_SCAN:
+                        stop = True
+                        break
+        candidates.sort(key=lambda c: (c["access_count"], c["importance"]), reverse=True)
+        top_patterns = candidates[:10]
+    except Exception:
+        top_patterns = []
+
+    return {
+        "session_id": raw.get("session_id"),
+        "discovery_tokens": discovery_tokens,
+        "read_tokens": read_tokens,
+        "total_tokens": discovery_tokens + read_tokens,
+        "cache_hits": cache_hits,
+        "cache_misses": cache_misses,
+        "hit_rate": hit_rate,
+        "ratio": raw.get("ratio", 0.0),
+        "savings_percent": raw.get("savings_percent", 0.0),
+        "top_patterns": top_patterns,
+        # Backward-compat aliases (pre-v7.7.21 camelCase consumers)
+        "discoveryTokens": discovery_tokens,
+        "readTokens": read_tokens,
+        "savingsPercent": raw.get("savings_percent", 0.0),
+        "raw": raw,
+    }
 
 
 @app.post("/api/memory/consolidate", dependencies=[Depends(auth.require_scope("control"))])

package/dashboard/static/index.html

@@ -632,6 +632,55 @@
           <div>
             <h3 style="font-family: 'DM Serif Display', Georgia, serif; font-size: 1.15rem; font-weight: 400; color: var(--loki-text-primary); margin-bottom: 12px;">Memory</h3>
             <loki-memory-browser id="memory-browser" tab="summary"></loki-memory-browser>
+            <!-- v7.7.21 token economics tile: hit rate + tokens + top patterns -->
+            <div id="memory-economics-tile" style="margin-top: 12px; background: var(--loki-bg-card, #1a1a1a); border: 1px solid var(--loki-border, #333); border-radius: 5px; padding: 12px;">
+              <div style="font-size: 11px; color: var(--loki-text-muted, #888); margin-bottom: 8px;">Token Economics</div>
+              <div id="memory-economics-metrics" style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; font-size: 13px;">
+                <div><span style="color: var(--loki-text-muted, #888);">Hit rate</span><br><strong id="econ-hit-rate">--</strong></div>
+                <div><span style="color: var(--loki-text-muted, #888);">Total tokens</span><br><strong id="econ-total-tokens">--</strong></div>
+                <div><span style="color: var(--loki-text-muted, #888);">Savings</span><br><strong id="econ-savings">--</strong></div>
+              </div>
+              <div id="memory-economics-top" style="margin-top: 10px; font-size: 12px; color: var(--loki-text-muted, #888);"></div>
+            </div>
+            <script>
+              (function(){
+                function loadEconomics(){
+                  fetch('/api/memory/economics').then(function(r){ return r.json(); }).then(function(j){
+                    var hr = document.getElementById('econ-hit-rate');
+                    var tt = document.getElementById('econ-total-tokens');
+                    var sv = document.getElementById('econ-savings');
+                    var top = document.getElementById('memory-economics-top');
+                    if (hr) hr.textContent = ((j.hit_rate || 0) * 100).toFixed(1) + '%';
+                    if (tt) tt.textContent = (j.total_tokens || 0).toLocaleString();
+                    if (sv) sv.textContent = (j.savings_percent || 0).toFixed(1) + '%';
+                    if (top) {
+                      var patterns = j.top_patterns || [];
+                      // v7.7.21 council fix (Opus 1): build DOM with
+                      // textContent (NOT innerHTML single-char escape) so
+                      // agent/PRD-derived summaries cannot inject markup.
+                      while (top.firstChild) top.removeChild(top.firstChild);
+                      if (patterns.length === 0) {
+                        top.textContent = 'No retrieval patterns yet. Run sessions to accumulate.';
+                      } else {
+                        var header = document.createElement('div');
+                        header.style.marginBottom = '4px';
+                        header.textContent = 'Top retrieved:';
+                        top.appendChild(header);
+                        patterns.slice(0, 5).forEach(function(p){
+                          var row = document.createElement('div');
+                          // textContent escapes everything; no markup injection.
+                          row.textContent = (p.access_count || 0) + 'x · ' +
+                            (p.summary || p.id || '');
+                          top.appendChild(row);
+                        });
+                      }
+                    }
+                  }).catch(function(){ /* endpoint not available; tile stays at -- */ });
+                }
+                loadEconomics();
+                setInterval(loadEconomics, 30000);
+              })();
+            </script>
           </div>
           <div>
             <h3 style="font-family: 'DM Serif Display', Georgia, serif; font-size: 1.15rem; font-weight: 400; color: var(--loki-text-primary); margin-bottom: 12px;">Memory Files</h3>

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.7.20
+**Version:** v7.7.22
 
 ---
 

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var _7=Object.defineProperty;var I7=(K)=>K;function P7(K,$){this[K]=I7.bind(null,$)}var v=(K,$)=>{for(var Q in $)_7(K,Q,{get:$[Q],enumerable:!0,configurable:!0,set:P7.bind($,Q)})};var R=(K,$)=>()=>(K&&($=K(K=0)),$);var t=import.meta.require;var e1={};v(e1,{lokiDir:()=>P,homeLokiDir:()=>k1,findRepoRootForVersion:()=>N1,REPO_ROOT:()=>p});import{resolve as u,dirname as S1}from"path";import{fileURLToPath as L7}from"url";import{existsSync as J1}from"fs";import{homedir as R7}from"os";function E7(){let K=i1;for(let $=0;$<6;$++){if(J1(u(K,"VERSION"))&&J1(u(K,"autonomy/run.sh")))return K;let Q=S1(K);if(Q===K)break;K=Q}return u(i1,"..","..","..")}function N1(K){let $=K;for(let Q=0;Q<6;Q++){if(J1(u($,"VERSION"))&&J1(u($,"autonomy/run.sh")))return $;let X=S1($);if(X===$)break;$=X}return u(K,"..","..","..")}function P(){return process.env.LOKI_DIR??u(process.cwd(),".loki")}function k1(){return u(R7(),".loki")}var i1,p;var g=R(()=>{i1=S1(L7(import.meta.url));p=E7()});import{readFileSync as F7}from"fs";import{resolve as w7,dirname as x7}from"path";import{fileURLToPath as S7}from"url";function G1(){if(o!==null)return o;let K="7.7.20";if(typeof K==="string"&&K.length>0)return o=K,o;try{let $=x7(S7(import.meta.url)),Q=N1($);o=F7(w7(Q,"VERSION"),"utf-8").trim()}catch{o="unknown"}return o}var o=null;var D1=R(()=>{g()});var $0={};v($0,{runOrThrow:()=>N7,run:()=>k,commandVersion:()=>D7,commandExists:()=>h,ShellError:()=>C1});async function k(K,$={}){let Q=Bun.spawn({cmd:[...K],stdout:"pipe",stderr:"pipe",env:$.env?{...process.env,...$.env}:process.env,cwd:$.cwd}),X,Z;if($.timeoutMs&&$.timeoutMs>0)X=setTimeout(()=>{try{Q.kill("SIGTERM")}catch{}Z=setTimeout(()=>{try{Q.kill("SIGKILL")}catch{}},2000)},$.timeoutMs);try{let[W,z,q]=await Promise.all([new Response(Q.stdout).text(),new Response(Q.stderr).text(),Q.exited]);return{stdout:W,stderr:z,exitCode:q}}finally{if(X)clearTimeout(X);if(Z)clearTimeout(Z)}}async function N7(K,$={}){let Q=await k(K,$);if(Q.exitCode!==0)throw new C1(`command failed (${Q.exitCode}): ${K.join(" ")}`,Q.exitCode,Q.stdout,Q.stderr);return Q}async function h(K){let $=k7(K),Q=await k(["sh","-c",`command -v ${$}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function k7(K){if(!/^[A-Za-z0-9._/-]+$/.test(K))throw Error(`refused to shell-escape suspect token: ${K}`);return K}async function D7(K,$="--version"){if(!await h(K))return null;let X=await k([K,$],{timeoutMs:5000});if(X.exitCode!==0)return null;return((X.stdout||X.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var C1;var n=R(()=>{C1=class C1 extends Error{message;exitCode;stdout;stderr;constructor(K,$,Q,X){super(K);this.message=K;this.exitCode=$;this.stdout=Q;this.stderr=X;this.name="ShellError"}}});function c(K){return C7?"":K}var C7,E,b,F,T6,O,D,w,H;var a=R(()=>{C7=(process.env.NO_COLOR??"").length>0;E=c("\x1B[0;31m"),b=c("\x1B[0;32m"),F=c("\x1B[1;33m"),T6=c("\x1B[0;34m"),O=c("\x1B[0;36m"),D=c("\x1B[1m"),w=c("\x1B[2m"),H=c("\x1B[0m")});import{existsSync as c7}from"fs";async function i(){if(X1!==void 0)return X1;let K="/opt/homebrew/bin/python3.12";if(c7(K))return X1=K,K;let $=await h("python3.12");if($)return X1=$,$;let Q=await h("python3");return X1=Q,Q}async function s(K,$={}){let Q=await i();if(!Q)return{stdout:"",stderr:"python3 not found",exitCode:127};return k([Q,"-c",K],$)}var X1;var Z1=R(()=>{n()});var G0={};v(G0,{runStatus:()=>Q5});import{existsSync as N,readFileSync as W1,readdirSync as W0,statSync as H0}from"fs";import{resolve as x,basename as a7}from"path";async function r7(){if(await h("jq"))return!0;return process.stdout.write(`${E}Error: jq is required but not installed.${H}
+var _7=Object.defineProperty;var I7=(K)=>K;function P7(K,$){this[K]=I7.bind(null,$)}var v=(K,$)=>{for(var Q in $)_7(K,Q,{get:$[Q],enumerable:!0,configurable:!0,set:P7.bind($,Q)})};var R=(K,$)=>()=>(K&&($=K(K=0)),$);var t=import.meta.require;var e1={};v(e1,{lokiDir:()=>P,homeLokiDir:()=>k1,findRepoRootForVersion:()=>N1,REPO_ROOT:()=>p});import{resolve as u,dirname as S1}from"path";import{fileURLToPath as L7}from"url";import{existsSync as J1}from"fs";import{homedir as R7}from"os";function E7(){let K=i1;for(let $=0;$<6;$++){if(J1(u(K,"VERSION"))&&J1(u(K,"autonomy/run.sh")))return K;let Q=S1(K);if(Q===K)break;K=Q}return u(i1,"..","..","..")}function N1(K){let $=K;for(let Q=0;Q<6;Q++){if(J1(u($,"VERSION"))&&J1(u($,"autonomy/run.sh")))return $;let X=S1($);if(X===$)break;$=X}return u(K,"..","..","..")}function P(){return process.env.LOKI_DIR??u(process.cwd(),".loki")}function k1(){return u(R7(),".loki")}var i1,p;var g=R(()=>{i1=S1(L7(import.meta.url));p=E7()});import{readFileSync as F7}from"fs";import{resolve as w7,dirname as x7}from"path";import{fileURLToPath as S7}from"url";function G1(){if(o!==null)return o;let K="7.7.22";if(typeof K==="string"&&K.length>0)return o=K,o;try{let $=x7(S7(import.meta.url)),Q=N1($);o=F7(w7(Q,"VERSION"),"utf-8").trim()}catch{o="unknown"}return o}var o=null;var D1=R(()=>{g()});var $0={};v($0,{runOrThrow:()=>N7,run:()=>k,commandVersion:()=>D7,commandExists:()=>h,ShellError:()=>C1});async function k(K,$={}){let Q=Bun.spawn({cmd:[...K],stdout:"pipe",stderr:"pipe",env:$.env?{...process.env,...$.env}:process.env,cwd:$.cwd}),X,Z;if($.timeoutMs&&$.timeoutMs>0)X=setTimeout(()=>{try{Q.kill("SIGTERM")}catch{}Z=setTimeout(()=>{try{Q.kill("SIGKILL")}catch{}},2000)},$.timeoutMs);try{let[W,z,q]=await Promise.all([new Response(Q.stdout).text(),new Response(Q.stderr).text(),Q.exited]);return{stdout:W,stderr:z,exitCode:q}}finally{if(X)clearTimeout(X);if(Z)clearTimeout(Z)}}async function N7(K,$={}){let Q=await k(K,$);if(Q.exitCode!==0)throw new C1(`command failed (${Q.exitCode}): ${K.join(" ")}`,Q.exitCode,Q.stdout,Q.stderr);return Q}async function h(K){let $=k7(K),Q=await k(["sh","-c",`command -v ${$}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function k7(K){if(!/^[A-Za-z0-9._/-]+$/.test(K))throw Error(`refused to shell-escape suspect token: ${K}`);return K}async function D7(K,$="--version"){if(!await h(K))return null;let X=await k([K,$],{timeoutMs:5000});if(X.exitCode!==0)return null;return((X.stdout||X.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var C1;var n=R(()=>{C1=class C1 extends Error{message;exitCode;stdout;stderr;constructor(K,$,Q,X){super(K);this.message=K;this.exitCode=$;this.stdout=Q;this.stderr=X;this.name="ShellError"}}});function c(K){return C7?"":K}var C7,E,b,F,T6,O,D,w,H;var a=R(()=>{C7=(process.env.NO_COLOR??"").length>0;E=c("\x1B[0;31m"),b=c("\x1B[0;32m"),F=c("\x1B[1;33m"),T6=c("\x1B[0;34m"),O=c("\x1B[0;36m"),D=c("\x1B[1m"),w=c("\x1B[2m"),H=c("\x1B[0m")});import{existsSync as c7}from"fs";async function i(){if(X1!==void 0)return X1;let K="/opt/homebrew/bin/python3.12";if(c7(K))return X1=K,K;let $=await h("python3.12");if($)return X1=$,$;let Q=await h("python3");return X1=Q,Q}async function s(K,$={}){let Q=await i();if(!Q)return{stdout:"",stderr:"python3 not found",exitCode:127};return k([Q,"-c",K],$)}var X1;var Z1=R(()=>{n()});var G0={};v(G0,{runStatus:()=>Q5});import{existsSync as N,readFileSync as W1,readdirSync as W0,statSync as H0}from"fs";import{resolve as x,basename as a7}from"path";async function r7(){if(await h("jq"))return!0;return process.stdout.write(`${E}Error: jq is required but not installed.${H}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -585,4 +585,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${$}
 `),process.stderr.write(j7),2}}process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var X6=await Q6(Bun.argv.slice(2));process.exit(X6);
 
-//# debugId=E25419B4237E69C764756E2164756E21
+//# debugId=67ACBDA1E9391E4564756E2164756E21

package/mcp/__init__.py

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

package/memory/replay.py

@@ -0,0 +1,192 @@
+"""v7.7.22: deterministic READ-ONLY session replay.
+
+Wow feature 1 from the memory excellence bar: no competitor offers
+session replay. `loki memory replay <episode-id>` re-renders a past
+episode's recorded action sequence as a timeline, annotated with the
+CURRENT state of each touched file (still exists? changed since the
+episode? present in git?). This answers "what did that session do, and
+what has changed since" without re-executing anything.
+
+DESIGN DECISION (v7.7.22): replay is READ-ONLY. It does NOT re-run the
+recorded tool_use sequence. LLM tool_uses are non-deterministic and
+re-running Edit/Write against the current repo could clobber
+uncommitted work. The `--apply` re-execution mode is deliberately
+deferred to a future release with proper sandboxing + confirmation.
+
+Output: a structured dict (the CLI renders Markdown or emits JSON).
+Never raises; returns an error dict on failure.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def _file_changed_since(repo_root: str, file_path: str, since_iso: Optional[str]) -> str:
+    """Return a current-state annotation for `file_path`.
+
+    One of: "missing", "unchanged-since", "changed-since",
+    "exists-no-timestamp", "exists-not-in-git". Best-effort; never raises.
+    """
+    abs_path = file_path if os.path.isabs(file_path) else os.path.join(repo_root, file_path)
+    if not os.path.exists(abs_path):
+        return "missing"
+    if not since_iso:
+        return "exists-no-timestamp"
+    # Use git to see if the file changed after the episode timestamp.
+    try:
+        # Normalize the ISO timestamp for git --since.
+        since = since_iso.replace("Z", "+00:00")
+        result = subprocess.run(
+            ["git", "-C", repo_root, "log", "--oneline", f"--since={since}", "--", file_path],
+            capture_output=True, text=True, timeout=10,
+        )
+        if result.returncode != 0:
+            return "exists-not-in-git"
+        commits = [ln for ln in result.stdout.splitlines() if ln.strip()]
+        return "changed-since" if commits else "unchanged-since"
+    except (subprocess.SubprocessError, OSError):
+        return "exists-no-timestamp"
+
+
+def replay_episode(
+    episode_id: str,
+    memory_base: str,
+    repo_root: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Build a read-only replay report for `episode_id`.
+
+    Args:
+        episode_id: The episode id (without the `task-` prefix).
+        memory_base: Path to the project's `.loki/memory/` directory.
+        repo_root: Repo root for current-state annotations. Defaults to
+            the parent-of-parent of memory_base (i.e. the project root).
+
+    Returns:
+        dict: {episode_id, found, timestamp, goal, outcome, agent,
+        timeline:[{step, tool, target, timestamp}], files:[{path,
+        state}], summary:{steps, files_touched, files_missing,
+        files_changed_since}} or {error: ...}.
+    """
+    try:
+        from memory.storage import MemoryStorage
+        storage = MemoryStorage(memory_base)
+        episode = storage.load_episode(episode_id)
+        if episode is None:
+            return {"episode_id": episode_id, "found": False,
+                    "error": f"episode '{episode_id}' not found in {memory_base}"}
+
+        if repo_root is None:
+            # memory_base is typically <root>/.loki/memory
+            repo_root = str(Path(memory_base).resolve().parent.parent)
+
+        ts = episode.get("timestamp")
+        context = episode.get("context", {}) if isinstance(episode.get("context"), dict) else {}
+        goal = context.get("goal") or episode.get("goal") or episode.get("summary", "")
+
+        # Timeline from action_log (v7.7.18 format). Fall back to
+        # tools_used (older episode format) if action_log is empty.
+        timeline: List[Dict[str, Any]] = []
+        action_log = episode.get("action_log") or []
+        if action_log:
+            for i, a in enumerate(action_log, 1):
+                if isinstance(a, dict):
+                    timeline.append({
+                        "step": i,
+                        "tool": a.get("action", a.get("tool", "?")),
+                        "target": a.get("target", a.get("input", "")),
+                        "timestamp": a.get("t", a.get("timestamp", 0)),
+                    })
+        else:
+            for i, t in enumerate(episode.get("tools_used", []) or [], 1):
+                timeline.append({"step": i, "tool": str(t), "target": "", "timestamp": 0})
+
+        # Current-state annotations for touched files.
+        touched = []
+        seen = set()
+        for f in (episode.get("files_modified") or []) + (episode.get("files_changed") or []):
+            if f and f not in seen:
+                seen.add(f)
+                touched.append(f)
+        files = []
+        missing = 0
+        changed = 0
+        for f in touched:
+            state = _file_changed_since(repo_root, f, ts)
+            if state == "missing":
+                missing += 1
+            elif state == "changed-since":
+                changed += 1
+            files.append({"path": f, "state": state})
+
+        return {
+            "episode_id": episode_id,
+            "found": True,
+            "timestamp": ts,
+            "goal": str(goal)[:500],
+            "outcome": episode.get("outcome", "unknown"),
+            "agent": episode.get("agent", "unknown"),
+            "timeline": timeline,
+            "files": files,
+            "summary": {
+                "steps": len(timeline),
+                "files_touched": len(touched),
+                "files_missing": missing,
+                "files_changed_since": changed,
+            },
+            "mode": "read-only (dry-run); --apply re-execution deferred to a future release",
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+        }
+    except Exception as e:
+        return {"episode_id": episode_id, "found": False, "error": str(e)}
+
+
+def render_markdown(report: Dict[str, Any]) -> str:
+    """Render a replay report dict as a human-readable Markdown timeline."""
+    if not report.get("found"):
+        return f"# Replay: {report.get('episode_id', '?')}\n\nNot found: {report.get('error', 'unknown error')}\n"
+    # v7.7.22 council fix (Opus 2): use .get() defaults throughout so a
+    # hand-built or partial report dict cannot KeyError. The CLI always
+    # passes a complete replay_episode() result, but render_markdown is
+    # public and may be called with sparse input.
+    lines = [
+        f"# Replay: {report.get('episode_id', '?')}",
+        "",
+        f"- Goal: {report.get('goal', '')}",
+        f"- Outcome: {report.get('outcome')}",
+        f"- Agent: {report.get('agent')}",
+        f"- Recorded: {report.get('timestamp')}",
+        f"- Mode: {report.get('mode')}",
+        "",
+        "## Timeline",
+        "",
+    ]
+    timeline = report.get("timeline") or []
+    if timeline:
+        for step in timeline:
+            lines.append(f"{step.get('step', '?')}. **{step.get('tool', '?')}** {step.get('target', '')}")
+    else:
+        lines.append("(no recorded actions)")
+    lines += ["", "## Files touched (current state)", ""]
+    files = report.get("files") or []
+    if files:
+        for f in files:
+            lines.append(f"- `{f.get('path', '?')}` -- {f.get('state', '?')}")
+    else:
+        lines.append("(none)")
+    s = report.get("summary") or {}
+    lines += [
+        "",
+        "## Summary",
+        "",
+        f"- Steps: {s['steps']}",
+        f"- Files touched: {s['files_touched']}",
+        f"- Now missing: {s['files_missing']}",
+        f"- Changed since episode: {s['files_changed_since']}",
+        "",
+    ]
+    return "\n".join(lines)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "7.7.20",
+  "version": "7.7.22",
   "description": "Loki Mode by Autonomi. Multi-agent autonomous SDLC framework. Spec to deployed app: PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief. 4 AI providers (Claude Code, OpenAI Codex, Cline, Aider). 11 quality gates.",
   "keywords": [
     "agent",