loki-mode 5.33.0 → 5.35.0

package/README.md

@@ -304,14 +304,14 @@ Last Updated: 2026-01-04 20:45:32
 
 **Access the dashboard:**
 ```bash
-# Automatically opens when running autonomously
+# Automatically starts when running autonomously
 ./autonomy/run.sh ./docs/requirements.md
 
 # Or open manually
-open .loki/dashboard/index.html
+open http://localhost:57374
 ```
 
-Auto-refreshes every 3 seconds. Works with any modern browser.
+The dashboard at `http://localhost:57374` auto-refreshes via WebSocket. Works with any modern browser.
 
 ---
 
@@ -488,7 +488,7 @@ graph TB
 
 ---
 
-## CLI Commands (v4.1.0)
+## CLI Commands
 
 The `loki` CLI provides easy access to all Loki Mode features:
 
@@ -663,7 +663,7 @@ loki memory retrieve "query"  # Test task-aware retrieval
 ```
 
 **API Endpoints:**
-- `GET /api/memory` - Memory summary
+- `GET /api/memory/summary` - Memory summary
 - `POST /api/memory/retrieve` - Query memories
 - `POST /api/memory/consolidate` - Trigger consolidation
 - `GET /api/memory/economics` - Token economics

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes PRD to deployed product with zero human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v5.33.0
+# Loki Mode v5.35.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -149,6 +149,7 @@ GROWTH ──[continuous improvement loop]──> GROWTH
 | `.loki/queue/dead-letter.json` | Session start | On task failure (5+ attempts) |
 | `.loki/signals/CONTEXT_CLEAR_REQUESTED` | Never | When context heavy |
 | `.loki/signals/HUMAN_REVIEW_NEEDED` | Never | When human decision required |
+| `.loki/state/checkpoints/` | After task completion | Automatic + manual via `loki checkpoint` |
 
 ---
 
@@ -254,9 +255,9 @@ The following features are documented in skill modules but not yet fully automat
 | Feature | Status | Notes |
 |---------|--------|-------|
 | PRE-ACT goal drift detection | Planned | Agent-level attention check before each action; no automated enforcement yet |
-| CONTINUITY.md working memory | Planned | Referenced in run.sh prompts but not automatically managed |
+| CONTINUITY.md working memory | Implemented (v5.35.0) | Auto-managed by run.sh, updated each iteration |
 | GitHub issue import | Planned | Config flags exist (`LOKI_GITHUB_IMPORT`); `gh` CLI integration partial |
-| Quality gates 3-reviewer system | Planned | Instructions in `skills/quality-gates.md`; not automated |
+| Quality gates 3-reviewer system | Implemented (v5.35.0) | 5 specialist reviewers in `skills/quality-gates.md`; execution in run.sh |
 | Benchmarks (HumanEval, SWE-bench) | Infrastructure only | Runner scripts and datasets exist in `benchmarks/`; no published results |
 
-**v5.33.0 | audit cleanup, honest feature claims | ~260 lines core**
+**v5.35.0 | checkpoint/restore, GitHub Action provider-agnostic | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-5.33.0
+5.35.0

package/api/README.md

@@ -33,7 +33,7 @@ brew install deno
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `LOKI_API_PORT` | `8420` | Server port |
+| `LOKI_DASHBOARD_PORT` | `57374` | Server port |
 | `LOKI_API_HOST` | `localhost` | Server host |
 | `LOKI_API_TOKEN` | none | API token for remote access |
 | `LOKI_DIR` | auto | Loki installation directory |

package/api/server.js

@@ -33,7 +33,7 @@ const { EventEmitter } = require('events');
 // Configuration
 //=============================================================================
 
-const DEFAULT_PORT = 9898;
+const DEFAULT_PORT = 57374;
 const DEFAULT_HOST = '127.0.0.1';
 const PROJECT_DIR = process.env.LOKI_PROJECT_DIR || process.cwd();
 

package/api/server.ts

@@ -84,8 +84,8 @@ interface ServerConfig {
 }
 
 const defaultConfig: ServerConfig = {
-  port: parseInt(Deno.env.get("LOKI_API_PORT") || "8420", 10),
-  host: Deno.env.get("LOKI_API_HOST") || "localhost",
+  port: parseInt(Deno.env.get("LOKI_DASHBOARD_PORT") || "57374", 10),
+  host: Deno.env.get("LOKI_DASHBOARD_HOST") || "localhost",
   cors: true,
   auth: true,
 };
@@ -365,15 +365,15 @@ Usage:
   deno run --allow-all api/server.ts [options]
 
 Options:
-  --port, -p <port>   Port to listen on (default: 8420)
+  --port, -p <port>   Port to listen on (default: 57374)
   --host, -h <host>   Host to bind to (default: localhost)
   --no-cors           Disable CORS
   --no-auth           Disable authentication
   --help              Show this help message
 
 Environment Variables:
-  LOKI_API_PORT       Port (overridden by --port)
-  LOKI_API_HOST       Host (overridden by --host)
+  LOKI_DASHBOARD_PORT Port (overridden by --port)
+  LOKI_DASHBOARD_HOST Host (overridden by --host)
   LOKI_API_TOKEN      API token for remote access
   LOKI_DIR            Loki installation directory
   LOKI_VERSION        Version string

package/api/test.js

@@ -34,7 +34,7 @@ const fs = require('fs');
 // Test Configuration
 //=============================================================================
 
-const PORT = 19898; // Use a different port for testing (9898 + 10000)
+const PORT = 67374; // Use a different port for testing (57374 + 10000)
 const HOST = '127.0.0.1';
 const BASE_URL = `http://${HOST}:${PORT}`;
 const SERVER_PATH = path.join(__dirname, 'server.js');

package/autonomy/api-server.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 /**
- * Loki Mode HTTP API Server (v1.2.0)
+ * Loki Mode HTTP API Server (v1.2.0) - LEGACY
+ * NOTE: The production API is now the unified FastAPI server at dashboard/server.py (port 57374)
+ * This file is kept for backward compatibility only.
  * Zero npm dependencies - uses only Node.js built-ins
  *
  * Usage:
- *   node autonomy/api-server.js [--port 9898]
- *   LOKI_API_PORT=9898 node autonomy/api-server.js
+ *   node autonomy/api-server.js [--port 57374]
+ *   LOKI_DASHBOARD_PORT=57374 node autonomy/api-server.js
  *   loki api start
  *
  * Endpoints:
@@ -69,7 +71,7 @@ function parseArgs() {
 const cliArgs = parseArgs();
 
 // Configuration
-const PORT = cliArgs.port || parseInt(process.env.LOKI_API_PORT || '9898');
+const PORT = cliArgs.port || parseInt(process.env.LOKI_DASHBOARD_PORT || '57374');
 const MAX_BODY_SIZE = parseInt(process.env.LOKI_API_MAX_BODY || '1048576'); // 1MB default
 const LOKI_DIR = process.env.LOKI_DIR || path.join(process.cwd(), '.loki');
 const STATE_DIR = path.join(LOKI_DIR, 'state');

package/autonomy/completion-council.sh

@@ -823,6 +823,7 @@ council_aggregate_votes() {
     _THRESHOLD="$threshold" \
     _VERDICT="$verdict" \
     _VOTES="$votes_json" \
+    _ROUND_FILE="$round_file" \
     python3 -c "
 import json, os
 from datetime import datetime, timezone
@@ -836,7 +837,7 @@ round_data = {
     'verdict': os.environ['_VERDICT'],
     'votes': json.loads(os.environ['_VOTES'])
 }
-with open('$round_file', 'w') as f:
+with open(os.environ['_ROUND_FILE'], 'w') as f:
     json.dump(round_data, f, indent=2)
 " || log_warn "Failed to write round vote file"
 
@@ -926,6 +927,7 @@ council_devils_advocate_review() {
     _ROUND="$round" \
     _ISSUES="$issues_found" \
     _DETAILS="${issue_details:-none}" \
+    _DA_FILE="$da_file" \
     python3 -c "
 import json, os
 from datetime import datetime, timezone
@@ -936,7 +938,7 @@ da_result = {
     'details': os.environ['_DETAILS'],
     'override': int(os.environ['_ISSUES']) > 0
 }
-with open('$da_file', 'w') as f:
+with open(os.environ['_DA_FILE'], 'w') as f:
     json.dump(da_result, f, indent=2)
 " || log_warn "Failed to write devil's advocate result"
 

package/autonomy/hooks/store-episode.sh

@@ -21,7 +21,7 @@ sys.path.insert(0, cwd)
 try:
     from memory.engine import MemoryEngine
     from memory.schemas import EpisodeTrace
-    from datetime import datetime
+    from datetime import datetime, timezone
     import json
 
     engine = MemoryEngine(os.path.join(cwd, '.loki/memory'))
@@ -30,7 +30,7 @@ try:
     episode = EpisodeTrace(
         id=session_id,
         task_id=f'session-{session_id}',
-        timestamp=datetime.utcnow(),
+        timestamp=datetime.now(timezone.utc),
         duration_seconds=0,
         agent='loki-mode',
         phase='session',

package/autonomy/loki

@@ -310,8 +310,8 @@ show_help() {
     echo "  logs             Show recent log output"
     echo "  dashboard [cmd]  Dashboard server (start|stop|status|url|open)"
     echo "  provider [cmd]   Manage AI provider (show|set|list|info)"
-    echo "  serve            Start HTTP API server (alias for api start)"
-    echo "  api [cmd]        HTTP API server (start|stop|status)"
+    echo "  serve            Start dashboard/API server (alias for api start)"
+    echo "  api [cmd]        Dashboard/API server (start|stop|status)"
     echo "  sandbox [cmd]    Docker sandbox (start|stop|status|logs|shell|build)"
     echo "  notify [cmd]     Send notifications (test|slack|discord|webhook|status)"
     echo "  voice [cmd]      Voice input for PRD creation (status|listen|dictate|speak|start)"
@@ -2762,18 +2762,17 @@ cmd_logs() {
     tail -n "$lines" "$log_file"
 }
 
-# API server management
+# API server management (delegates to unified FastAPI dashboard server)
 cmd_api() {
     local subcommand="${1:-help}"
-    local port="${LOKI_API_PORT:-9898}"
-    local pid_file="$LOKI_DIR/api.pid"
-    local api_server="$SKILL_DIR/api/server.js"
+    local port="${LOKI_DASHBOARD_PORT:-57374}"
+    local pid_file="$LOKI_DIR/dashboard/dashboard.pid"
 
     case "$subcommand" in
         start)
-            # Check if Node.js is available
-            if ! command -v node &> /dev/null; then
-                echo -e "${RED}Error: Node.js not found. Install with: brew install node${NC}"
+            # Check if Python is available
+            if ! command -v python3 &> /dev/null; then
+                echo -e "${RED}Error: Python 3 not found. Install with: brew install python3${NC}"
                 exit 1
             fi
 
@@ -2781,19 +2780,19 @@ cmd_api() {
             if [ -f "$pid_file" ]; then
                 local existing_pid=$(cat "$pid_file")
                 if kill -0 "$existing_pid" 2>/dev/null; then
-                    echo -e "${YELLOW}API server already running (PID: $existing_pid)${NC}"
+                    echo -e "${YELLOW}Dashboard server already running (PID: $existing_pid)${NC}"
                     echo "URL: http://localhost:$port"
                     exit 0
                 fi
             fi
 
             # Start server
-            mkdir -p "$LOKI_DIR/logs"
-            nohup node "$api_server" --port "$port" > "$LOKI_DIR/logs/api.log" 2>&1 &
+            mkdir -p "$LOKI_DIR/logs" "$LOKI_DIR/dashboard"
+            LOKI_DIR="$LOKI_DIR" nohup python3 -m uvicorn dashboard.server:app --host 0.0.0.0 --port "$port" > "$LOKI_DIR/logs/api.log" 2>&1 &
             local new_pid=$!
             echo "$new_pid" > "$pid_file"
 
-            echo -e "${GREEN}API server started${NC}"
+            echo -e "${GREEN}Dashboard server started${NC}"
             echo "  PID:  $new_pid"
             echo "  URL:  http://localhost:$port"
             echo "  Logs: $LOKI_DIR/logs/api.log"
@@ -2805,13 +2804,13 @@ cmd_api() {
                 if kill -0 "$pid" 2>/dev/null; then
                     kill "$pid"
                     rm -f "$pid_file"
-                    echo -e "${GREEN}API server stopped${NC}"
+                    echo -e "${GREEN}Dashboard server stopped${NC}"
                 else
                     rm -f "$pid_file"
-                    echo -e "${YELLOW}API server was not running${NC}"
+                    echo -e "${YELLOW}Dashboard server was not running${NC}"
                 fi
             else
-                echo -e "${YELLOW}No API server PID file found${NC}"
+                echo -e "${YELLOW}No dashboard server PID file found${NC}"
             fi
             ;;
 
@@ -2819,7 +2818,7 @@ cmd_api() {
             if [ -f "$pid_file" ]; then
                 local pid=$(cat "$pid_file")
                 if kill -0 "$pid" 2>/dev/null; then
-                    echo -e "${GREEN}API server running${NC}"
+                    echo -e "${GREEN}Dashboard server running${NC}"
                     echo "  PID:  $pid"
                     echo "  URL:  http://localhost:$port"
 
@@ -2827,39 +2826,39 @@ cmd_api() {
                     if command -v curl &> /dev/null; then
                         echo ""
                         echo -e "${CYAN}Status:${NC}"
-                        curl -s "http://localhost:$port/status" 2>/dev/null | jq . 2>/dev/null || true
+                        curl -s "http://localhost:$port/api/status" 2>/dev/null | jq . 2>/dev/null || true
                     fi
                 else
-                    echo -e "${YELLOW}API server not running (stale PID file)${NC}"
+                    echo -e "${YELLOW}Dashboard server not running (stale PID file)${NC}"
                     rm -f "$pid_file"
                 fi
             else
-                echo -e "${YELLOW}API server not running${NC}"
+                echo -e "${YELLOW}Dashboard server not running${NC}"
             fi
             ;;
 
         *)
-            echo -e "${BOLD}Loki Mode API Server${NC}"
+            echo -e "${BOLD}Loki Mode Dashboard/API Server${NC}"
             echo ""
             echo "Usage: loki api <command>"
             echo ""
             echo "Commands:"
-            echo "  start    Start the HTTP API server"
-            echo "  stop     Stop the API server"
-            echo "  status   Check if API server is running"
+            echo "  start    Start the unified FastAPI dashboard server"
+            echo "  stop     Stop the dashboard server"
+            echo "  status   Check if dashboard server is running"
             echo ""
             echo "Environment:"
-            echo "  LOKI_API_PORT  Port to listen on (default: 9898)"
+            echo "  LOKI_DASHBOARD_PORT  Port to listen on (default: 57374)"
             echo ""
             echo "Endpoints:"
-            echo "  GET  /health  - Health check"
-            echo "  GET  /status  - Session status"
-            echo "  GET  /events  - SSE stream"
-            echo "  GET  /logs    - Recent logs"
-            echo "  POST /start   - Start session"
-            echo "  POST /stop    - Stop session"
-            echo "  POST /pause   - Pause session"
-            echo "  POST /resume  - Resume session"
+            echo "  GET  /api/health  - Health check"
+            echo "  GET  /api/status  - Session status"
+            echo "  GET  /api/events  - SSE stream"
+            echo "  GET  /api/logs    - Recent logs"
+            echo "  POST /api/start   - Start session"
+            echo "  POST /api/stop    - Stop session"
+            echo "  POST /api/pause   - Pause session"
+            echo "  POST /api/resume  - Resume session"
             ;;
     esac
 }
@@ -4032,6 +4031,9 @@ main() {
         compound)
             cmd_compound "$@"
             ;;
+        checkpoint|cp)
+            cmd_checkpoint "$@"
+            ;;
         council)
             cmd_council "$@"
             ;;
@@ -5318,6 +5320,294 @@ COMPOUND_RUN_SCRIPT
     esac
 }
 
+# Checkpoint management - save and restore session state (v5.34.0)
+cmd_checkpoint() {
+    local subcommand="${1:-list}"
+    shift 2>/dev/null || true
+
+    local checkpoints_dir=".loki/state/checkpoints"
+    local index_file="$checkpoints_dir/index.jsonl"
+
+    case "$subcommand" in
+        list|ls)
+            echo -e "${BOLD}Session Checkpoints${NC}"
+            echo ""
+
+            if [ ! -f "$index_file" ]; then
+                echo "  No checkpoints yet."
+                echo ""
+                echo "  Create one with: loki checkpoint create [message]"
+                return 0
+            fi
+
+            local count=0
+            local lines=()
+            while IFS= read -r line; do
+                lines+=("$line")
+            done < "$index_file"
+
+            # Show last 10 entries (most recent last)
+            local total=${#lines[@]}
+            local start=0
+            if [ "$total" -gt 10 ]; then
+                start=$((total - 10))
+            fi
+
+            printf "  ${DIM}%-14s %-20s %-10s %s${NC}\n" "ID" "TIMESTAMP" "GIT SHA" "MESSAGE"
+
+            local i
+            for (( i=start; i<total; i++ )); do
+                local entry="${lines[$i]}"
+                local cp_id=$(echo "$entry" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('id',''))" 2>/dev/null)
+                local cp_ts=$(echo "$entry" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('timestamp','') or d.get('ts',''))" 2>/dev/null)
+                local cp_sha=$(echo "$entry" | python3 -c "import sys,json; d=json.load(sys.stdin); print((d.get('git_sha','') or d.get('sha',''))[:8])" 2>/dev/null)
+                local cp_msg=$(echo "$entry" | python3 -c "import sys,json; d=json.load(sys.stdin); print((d.get('message','') or d.get('task',''))[:50])" 2>/dev/null)
+
+                if [ -n "$cp_id" ]; then
+                    printf "  ${GREEN}%-14s${NC} %-20s ${CYAN}%-10s${NC} %s\n" "$cp_id" "$cp_ts" "$cp_sha" "$cp_msg"
+                    count=$((count + 1))
+                fi
+            done
+
+            if [ "$count" -eq 0 ]; then
+                echo "  No valid checkpoints found."
+            else
+                echo ""
+                echo "  Showing ${count} of ${total} checkpoints"
+            fi
+            ;;
+
+        create)
+            local raw_message="${*:-manual checkpoint}"
+            # Escape backslashes and double quotes for JSON safety
+            local message
+            message=$(printf '%s' "$raw_message" | sed 's/\\/\\\\/g; s/"/\\"/g' | head -c 200)
+
+            echo -e "${BOLD}Creating checkpoint...${NC}"
+            echo ""
+
+            # Ensure .loki exists
+            if [ ! -d ".loki" ]; then
+                echo -e "${RED}Error: No .loki directory found. Are you in a Loki project?${NC}"
+                return 1
+            fi
+
+            # Capture git info
+            local git_sha=""
+            local git_branch=""
+            if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+                git_sha=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+                git_branch=$(git branch --show-current 2>/dev/null || echo "unknown")
+            else
+                git_sha="not-a-git-repo"
+                git_branch="none"
+            fi
+
+            # Generate checkpoint ID with timestamp
+            local ts=$(date -u '+%Y%m%d-%H%M%S')
+            local cp_id="cp-${ts}"
+            local cp_dir="$checkpoints_dir/$cp_id"
+
+            # Create checkpoint directory
+            mkdir -p "$cp_dir"
+
+            # Copy state files
+            local copied=0
+            for item in .loki/session.json .loki/dashboard-state.json .loki/queue .loki/memory .loki/metrics .loki/council; do
+                if [ -e "$item" ]; then
+                    cp -r "$item" "$cp_dir/" 2>/dev/null && copied=$((copied + 1))
+                fi
+            done
+
+            # Write metadata (use python3 json.dumps for safe serialization)
+            local iso_ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+            # Truncate message to 500 chars to prevent abuse
+            local safe_message="${message:0:500}"
+            _CP_ID="$cp_id" _CP_TS="$iso_ts" _CP_SHA="$git_sha" _CP_BRANCH="$git_branch" \
+            _CP_MSG="$safe_message" _CP_FILES="$copied" _CP_DIR="$cp_dir" _CP_INDEX="$index_file" \
+            _CP_CHKDIR="$checkpoints_dir" python3 << 'WRITE_META_EOF'
+import json, os
+metadata = {
+    "id": os.environ["_CP_ID"],
+    "timestamp": os.environ["_CP_TS"],
+    "git_sha": os.environ["_CP_SHA"],
+    "git_branch": os.environ["_CP_BRANCH"],
+    "message": os.environ["_CP_MSG"],
+    "files_copied": int(os.environ["_CP_FILES"]),
+    "created_by": "loki checkpoint create"
+}
+cp_dir = os.environ["_CP_DIR"]
+os.makedirs(cp_dir, exist_ok=True)
+with open(os.path.join(cp_dir, "metadata.json"), "w") as f:
+    json.dump(metadata, f, indent=4)
+index_file = os.environ["_CP_INDEX"]
+os.makedirs(os.environ["_CP_CHKDIR"], exist_ok=True)
+with open(index_file, "a") as f:
+    index_entry = {
+        "id": metadata["id"],
+        "timestamp": metadata["timestamp"],
+        "git_sha": metadata["git_sha"],
+        "git_branch": metadata["git_branch"],
+        "message": metadata["message"],
+    }
+    f.write(json.dumps(index_entry) + "\n")
+WRITE_META_EOF
+
+            echo -e "  Checkpoint: ${GREEN}$cp_id${NC}"
+            echo -e "  Git SHA:    ${CYAN}${git_sha:0:8}${NC} ($git_branch)"
+            echo -e "  Message:    $message"
+            echo -e "  Files:      $copied state items copied"
+            echo -e "  Location:   $cp_dir"
+            echo ""
+            echo "  Restore with: loki checkpoint rollback $cp_id"
+            ;;
+
+        show)
+            local cp_id="${1:-}"
+            if [ -z "$cp_id" ]; then
+                echo -e "${RED}Error: Specify a checkpoint ID${NC}"
+                echo "Usage: loki checkpoint show <id>"
+                echo "Run 'loki checkpoint list' to see available checkpoints."
+                return 1
+            fi
+
+            # Validate checkpoint ID (prevent path traversal)
+            if [[ ! "$cp_id" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+                echo -e "${RED}Error: Invalid checkpoint ID (must be alphanumeric, hyphens, underscores only)${NC}"
+                return 1
+            fi
+
+            local cp_dir="$checkpoints_dir/$cp_id"
+            local metadata="$cp_dir/metadata.json"
+
+            if [ ! -f "$metadata" ]; then
+                echo -e "${RED}Error: Checkpoint not found: $cp_id${NC}"
+                echo "Run 'loki checkpoint list' to see available checkpoints."
+                return 1
+            fi
+
+            echo -e "${BOLD}Checkpoint: $cp_id${NC}"
+            echo ""
+
+            _CP_METADATA="$metadata" python3 << 'SHOW_EOF'
+import json, os
+with open(os.environ["_CP_METADATA"], "r") as f:
+    d = json.load(f)
+print(f"  ID:         {d.get('id', 'unknown')}")
+print(f"  Timestamp:  {d.get('timestamp', 'unknown')}")
+print(f"  Git SHA:    {d.get('git_sha', 'unknown')}")
+print(f"  Git Branch: {d.get('git_branch', 'unknown')}")
+print(f"  Message:    {d.get('message', 'none')}")
+print(f"  Files:      {d.get('files_copied', 0)} state items")
+print(f"  Created By: {d.get('created_by', 'unknown')}")
+SHOW_EOF
+
+            echo ""
+            echo "  Contents:"
+            for item in "$cp_dir"/*; do
+                [ -e "$item" ] || continue
+                local name=$(basename "$item")
+                [ "$name" = "metadata.json" ] && continue
+                if [ -d "$item" ]; then
+                    local fcount=$(find "$item" -type f 2>/dev/null | wc -l | tr -d ' ')
+                    echo -e "    ${DIM}[dir]${NC}  $name/ ($fcount files)"
+                else
+                    local fsize=$(wc -c < "$item" 2>/dev/null | tr -d ' ')
+                    echo -e "    ${DIM}[file]${NC} $name (${fsize} bytes)"
+                fi
+            done
+            ;;
+
+        rollback)
+            local cp_id="${1:-}"
+            if [ -z "$cp_id" ]; then
+                echo -e "${RED}Error: Specify a checkpoint ID${NC}"
+                echo "Usage: loki checkpoint rollback <id>"
+                echo "Run 'loki checkpoint list' to see available checkpoints."
+                return 1
+            fi
+
+            # Validate checkpoint ID (prevent path traversal)
+            if [[ ! "$cp_id" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+                echo -e "${RED}Error: Invalid checkpoint ID (must be alphanumeric, hyphens, underscores only)${NC}"
+                return 1
+            fi
+
+            local cp_dir="$checkpoints_dir/$cp_id"
+            local metadata="$cp_dir/metadata.json"
+
+            if [ ! -f "$metadata" ]; then
+                echo -e "${RED}Error: Checkpoint not found: $cp_id${NC}"
+                echo "Run 'loki checkpoint list' to see available checkpoints."
+                return 1
+            fi
+
+            echo -e "${BOLD}Rolling back to checkpoint: $cp_id${NC}"
+            echo ""
+
+            # Restore state files
+            local restored=0
+            for item in "$cp_dir"/*; do
+                [ -e "$item" ] || continue
+                local name=$(basename "$item")
+                [ "$name" = "metadata.json" ] && continue
+
+                if [ -d "$item" ]; then
+                    rm -rf ".loki/$name"
+                    cp -r "$item" ".loki/$name" 2>/dev/null && restored=$((restored + 1))
+                else
+                    cp "$item" ".loki/$name" 2>/dev/null && restored=$((restored + 1))
+                fi
+            done
+
+            echo -e "  Restored: ${GREEN}$restored${NC} state items from $cp_id"
+
+            # Show git info for manual code rollback
+            local cp_sha=$(_CP_METADATA="$metadata" python3 -c "import json, os; d=json.load(open(os.environ['_CP_METADATA'])); print(d.get('git_sha','unknown'))" 2>/dev/null)
+            if [ -n "$cp_sha" ] && [ "$cp_sha" != "unknown" ] && [ "$cp_sha" != "not-a-git-repo" ]; then
+                echo ""
+                echo -e "  ${YELLOW}Note:${NC} Session state has been restored, but code is unchanged."
+                echo "  To also roll back code to the checkpoint's git state:"
+                echo ""
+                echo -e "    ${DIM}git reset --hard ${cp_sha:0:8}${NC}"
+                echo ""
+                echo -e "  ${RED}Warning:${NC} git reset --hard will discard uncommitted changes."
+                echo "  Consider 'git stash' first to preserve current work."
+            fi
+            ;;
+
+        help|--help|-h)
+            echo -e "${BOLD}loki checkpoint${NC} - Session state checkpoints"
+            echo ""
+            echo "Save and restore session state snapshots during autonomous runs."
+            echo "Checkpoints capture .loki/ state files and record the git SHA"
+            echo "at the time of creation."
+            echo ""
+            echo "Usage: loki checkpoint <command> [args]"
+            echo "       loki cp <command> [args]"
+            echo ""
+            echo "Commands:"
+            echo "  list              List recent checkpoints (default)"
+            echo "  create [message]  Create a new checkpoint"
+            echo "  show <id>         Show checkpoint details"
+            echo "  rollback <id>     Restore state from a checkpoint"
+            echo "  help              Show this help"
+            echo ""
+            echo "Examples:"
+            echo "  loki checkpoint create 'before refactor'"
+            echo "  loki cp list"
+            echo "  loki cp show cp-20260212-143022"
+            echo "  loki cp rollback cp-20260212-143022"
+            ;;
+
+        *)
+            echo -e "${RED}Unknown checkpoint command: $subcommand${NC}"
+            echo "Run 'loki checkpoint help' for usage."
+            return 1
+            ;;
+    esac
+}
+
 # Completion Council management
 cmd_council() {
     local subcommand="${1:-status}"