loki-mode 5.33.0 → 5.34.0

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.34.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` |
 
 ---
 
@@ -259,4 +260,4 @@ The following features are documented in skill modules but not yet fully automat
 | Quality gates 3-reviewer system | Planned | Instructions in `skills/quality-gates.md`; not automated |
 | 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.34.0 | checkpoint/restore, GitHub Action provider-agnostic | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-5.33.0
+5.34.0

package/autonomy/loki

@@ -4032,6 +4032,9 @@ main() {
         compound)
             cmd_compound "$@"
             ;;
+        checkpoint|cp)
+            cmd_checkpoint "$@"
+            ;;
         council)
             cmd_council "$@"
             ;;
@@ -5318,6 +5321,263 @@ 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',''))" 2>/dev/null)
+                local cp_sha=$(echo "$entry" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('git_sha','')[:8])" 2>/dev/null)
+                local cp_msg=$(echo "$entry" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('message','')[: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 message="${*:-manual checkpoint}"
+
+            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
+            local iso_ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+            cat > "$cp_dir/metadata.json" << METADATA_EOF
+{
+    "id": "$cp_id",
+    "timestamp": "$iso_ts",
+    "git_sha": "$git_sha",
+    "git_branch": "$git_branch",
+    "message": "$message",
+    "files_copied": $copied,
+    "created_by": "loki checkpoint create"
+}
+METADATA_EOF
+
+            # Append to index
+            mkdir -p "$checkpoints_dir"
+            echo "{\"id\":\"$cp_id\",\"timestamp\":\"$iso_ts\",\"git_sha\":\"$git_sha\",\"git_branch\":\"$git_branch\",\"message\":\"$message\"}" >> "$index_file"
+
+            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
+
+            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 ""
+
+            python3 << SHOW_EOF
+import json, os
+with open("$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
+
+            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=$(python3 -c "import json; d=json.load(open('$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}"

package/autonomy/run.sh

@@ -3879,6 +3879,167 @@ if top:
 SOLUTIONS_SCRIPT
 }
 
+# ============================================================================
+# Checkpoint/Snapshot System (v5.34.0)
+# Git-based checkpoints after task completion with state snapshots
+# Inspired by Cursor Self-Driving Codebases + Entire.io provenance tracking
+# ============================================================================
+
+create_checkpoint() {
+    # Create a git checkpoint after task completion
+    # Args: $1 = task description, $2 = task_id (optional)
+    local task_desc="${1:-task completed}"
+    local task_id="${2:-unknown}"
+    local checkpoint_dir=".loki/state/checkpoints"
+    local iteration="${ITERATION_COUNT:-0}"
+
+    mkdir -p "$checkpoint_dir"
+
+    # Only checkpoint if there are uncommitted changes
+    if ! git diff --quiet 2>/dev/null && ! git diff --cached --quiet 2>/dev/null; then
+        log_info "No uncommitted changes to checkpoint"
+        return 0
+    fi
+
+    # Capture git state
+    local git_sha
+    git_sha=$(git rev-parse HEAD 2>/dev/null || echo "no-git")
+    local git_branch
+    git_branch=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+    # Snapshot .loki state files
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local checkpoint_id="cp-${iteration}-$(date +%s)"
+    local cp_dir="${checkpoint_dir}/${checkpoint_id}"
+
+    mkdir -p "$cp_dir"
+
+    # Copy critical state files (lightweight -- not full .loki/)
+    for f in state/orchestrator.json queue/pending.json queue/completed.json queue/in-progress.json queue/current-task.json; do
+        if [ -f ".loki/$f" ]; then
+            local target_dir="$cp_dir/$(dirname "$f")"
+            mkdir -p "$target_dir"
+            cp ".loki/$f" "$cp_dir/$f" 2>/dev/null || true
+        fi
+    done
+
+    # Write checkpoint metadata
+    local safe_desc
+    safe_desc=$(printf '%s' "$task_desc" | sed 's/\\/\\\\/g; s/"/\\"/g' | head -c 200)
+    cat > "$cp_dir/metadata.json" << CPEOF
+{
+  "id": "${checkpoint_id}",
+  "timestamp": "${timestamp}",
+  "iteration": ${iteration},
+  "task_id": "${task_id}",
+  "task_description": "${safe_desc}",
+  "git_sha": "${git_sha}",
+  "git_branch": "${git_branch}",
+  "provider": "${PROVIDER_NAME:-claude}",
+  "phase": "$(cat .loki/state/orchestrator.json 2>/dev/null | python3 -c 'import sys,json; print(json.load(sys.stdin).get("currentPhase","unknown"))' 2>/dev/null || echo 'unknown')"
+}
+CPEOF
+
+    # Maintain checkpoint index for fast listing
+    local index_file="${checkpoint_dir}/index.jsonl"
+    printf '{"id":"%s","ts":"%s","iter":%d,"task":"%s","sha":"%s"}\n' \
+        "$checkpoint_id" "$timestamp" "$iteration" "$safe_desc" "$git_sha" \
+        >> "$index_file"
+
+    # Retention: keep last 50 checkpoints, prune older
+    local cp_count
+    cp_count=$(find "$checkpoint_dir" -maxdepth 1 -type d -name "cp-*" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$cp_count" -gt 50 ]; then
+        local to_remove=$((cp_count - 50))
+        find "$checkpoint_dir" -maxdepth 1 -type d -name "cp-*" 2>/dev/null | sort | head -n "$to_remove" | while read -r old_cp; do
+            rm -r "$old_cp" 2>/dev/null || true
+        done
+        # Rebuild index from remaining checkpoints
+        : > "$index_file"
+        for remaining in "$checkpoint_dir"/cp-*/metadata.json; do
+            [ -f "$remaining" ] || continue
+            python3 -c "
+import json,sys
+m=json.load(open('$remaining'))
+print(json.dumps({'id':m['id'],'ts':m['timestamp'],'iter':m['iteration'],'task':m.get('task_description',''),'sha':m['git_sha']}))
+" >> "$index_file" 2>/dev/null || true
+        done
+    fi
+
+    log_info "Checkpoint created: ${checkpoint_id} (git: ${git_sha:0:8})"
+}
+
+rollback_to_checkpoint() {
+    # Rollback state files to a specific checkpoint
+    # Args: $1 = checkpoint_id
+    local checkpoint_id="$1"
+    local checkpoint_dir=".loki/state/checkpoints"
+    local cp_dir="${checkpoint_dir}/${checkpoint_id}"
+
+    if [ ! -d "$cp_dir" ]; then
+        log_error "Checkpoint not found: ${checkpoint_id}"
+        return 1
+    fi
+
+    # Read checkpoint metadata
+    local git_sha
+    git_sha=$(python3 -c "import json; print(json.load(open('${cp_dir}/metadata.json'))['git_sha'])" 2>/dev/null || echo "")
+
+    log_warn "Rolling back to checkpoint: ${checkpoint_id}"
+
+    # Create a pre-rollback checkpoint first
+    create_checkpoint "pre-rollback snapshot" "rollback"
+
+    # Restore state files
+    for f in state/orchestrator.json queue/pending.json queue/completed.json queue/in-progress.json queue/current-task.json; do
+        if [ -f "${cp_dir}/${f}" ]; then
+            local target_dir=".loki/$(dirname "$f")"
+            mkdir -p "$target_dir"
+            cp "${cp_dir}/${f}" ".loki/${f}" 2>/dev/null || true
+        fi
+    done
+
+    # Log the rollback
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    printf '{"event":"rollback","checkpoint":"%s","git_sha":"%s","timestamp":"%s"}\n' \
+        "$checkpoint_id" "$git_sha" "$timestamp" \
+        >> ".loki/events.jsonl" 2>/dev/null || true
+
+    log_info "State files restored from checkpoint: ${checkpoint_id}"
+
+    if [ -n "$git_sha" ] && [ "$git_sha" != "no-git" ]; then
+        log_info "Git SHA at checkpoint: ${git_sha}"
+        log_info "To rollback code: git reset --hard ${git_sha}"
+    fi
+}
+
+list_checkpoints() {
+    # List recent checkpoints
+    local checkpoint_dir=".loki/state/checkpoints"
+    local index_file="${checkpoint_dir}/index.jsonl"
+    local limit="${1:-10}"
+
+    if [ ! -f "$index_file" ]; then
+        echo "No checkpoints found."
+        return
+    fi
+
+    tail -n "$limit" "$index_file" | python3 -c "
+import sys, json
+lines = sys.stdin.readlines()
+for line in reversed(lines):
+    try:
+        cp = json.loads(line)
+        sha = cp.get('sha','')[:8]
+        task = cp.get('task','')[:60]
+        print(f\"  {cp['id']}  {cp['ts']}  [{sha}]  {task}\")
+    except:
+        continue
+"
+}
+
 start_dashboard() {
     log_header "Starting Loki Dashboard"
 
@@ -5795,6 +5956,9 @@ main() {
     # Compound learnings into structured solution files (v5.30.0)
     compound_session_to_solutions
 
+    # Create session-end checkpoint (v5.34.0)
+    create_checkpoint "session end (iterations=$ITERATION_COUNT)" "session-end"
+
     # Log session end for audit
     audit_log "SESSION_END" "result=$result,prd=$PRD_PATH"
 

package/dashboard/__init__.py

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

package/dashboard/server.py

@@ -1984,6 +1984,149 @@ async def force_council_review():
     return {"success": True, "message": "Council review requested"}
 
 
+# =============================================================================
+# Checkpoint API (v5.34.0)
+# =============================================================================
+
+class CheckpointCreate(BaseModel):
+    """Schema for creating a checkpoint."""
+    message: Optional[str] = Field(None, description="Optional description for the checkpoint")
+
+
+def _sanitize_checkpoint_id(checkpoint_id: str) -> str:
+    """Validate checkpoint_id contains only safe characters for file paths."""
+    if not checkpoint_id or ".." in checkpoint_id or not _SAFE_ID_RE.match(checkpoint_id):
+        raise HTTPException(
+            status_code=400,
+            detail="Invalid checkpoint_id: must contain only alphanumeric characters, hyphens, and underscores",
+        )
+    return checkpoint_id
+
+
+@app.get("/api/checkpoints")
+async def list_checkpoints(limit: int = Query(default=20, ge=1, le=200)):
+    """List recent checkpoints from index.jsonl."""
+    loki_dir = _get_loki_dir()
+    index_file = loki_dir / "state" / "checkpoints" / "index.jsonl"
+    checkpoints = []
+
+    if index_file.exists():
+        try:
+            for line in index_file.read_text().strip().split("\n"):
+                if line.strip():
+                    try:
+                        checkpoints.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        pass
+        except Exception:
+            pass
+
+    # Return most recent first, limited
+    checkpoints.reverse()
+    return checkpoints[:limit]
+
+
+@app.get("/api/checkpoints/{checkpoint_id}")
+async def get_checkpoint(checkpoint_id: str):
+    """Get checkpoint details by ID."""
+    checkpoint_id = _sanitize_checkpoint_id(checkpoint_id)
+    loki_dir = _get_loki_dir()
+    metadata_file = loki_dir / "state" / "checkpoints" / checkpoint_id / "metadata.json"
+
+    if not metadata_file.exists():
+        raise HTTPException(status_code=404, detail="Checkpoint not found")
+
+    try:
+        return json.loads(metadata_file.read_text())
+    except (json.JSONDecodeError, IOError) as e:
+        raise HTTPException(status_code=500, detail=f"Failed to read checkpoint: {e}")
+
+
+@app.post("/api/checkpoints", status_code=201)
+async def create_checkpoint(body: CheckpointCreate = None):
+    """Create a new checkpoint capturing current state."""
+    import subprocess
+    import shutil
+
+    loki_dir = _get_loki_dir()
+    checkpoints_dir = loki_dir / "state" / "checkpoints"
+    checkpoints_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate checkpoint ID from timestamp
+    now = datetime.now(timezone.utc)
+    checkpoint_id = now.strftime("chk-%Y%m%d-%H%M%S")
+
+    # Create checkpoint directory
+    checkpoint_dir = checkpoints_dir / checkpoint_id
+    checkpoint_dir.mkdir(parents=True, exist_ok=True)
+
+    # Capture git SHA
+    git_sha = ""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0:
+            git_sha = result.stdout.strip()
+    except Exception:
+        pass
+
+    # Copy key state files into checkpoint
+    state_files = [
+        "dashboard-state.json",
+        "session.json",
+    ]
+    for fname in state_files:
+        src = loki_dir / fname
+        if src.exists():
+            try:
+                shutil.copy2(str(src), str(checkpoint_dir / fname))
+            except Exception:
+                pass
+
+    # Copy queue directory if present
+    queue_src = loki_dir / "queue"
+    if queue_src.exists():
+        try:
+            shutil.copytree(str(queue_src), str(checkpoint_dir / "queue"), dirs_exist_ok=True)
+        except Exception:
+            pass
+
+    # Build metadata
+    message = ""
+    if body and body.message:
+        message = body.message
+
+    metadata = {
+        "id": checkpoint_id,
+        "created_at": now.isoformat(),
+        "git_sha": git_sha,
+        "message": message,
+        "files": [f.name for f in checkpoint_dir.iterdir() if f.is_file()],
+    }
+
+    # Write metadata.json
+    (checkpoint_dir / "metadata.json").write_text(json.dumps(metadata, indent=2))
+
+    # Append to index.jsonl
+    index_file = checkpoints_dir / "index.jsonl"
+    with open(str(index_file), "a") as f:
+        f.write(json.dumps(metadata) + "\n")
+
+    # Retention policy: keep last 50 checkpoints
+    MAX_CHECKPOINTS = 50
+    all_dirs = sorted(
+        [d for d in checkpoints_dir.iterdir() if d.is_dir()],
+        key=lambda d: d.name,
+    )
+    while len(all_dirs) > MAX_CHECKPOINTS:
+        oldest = all_dirs.pop(0)
+        shutil.rmtree(str(oldest), ignore_errors=True)
+
+    return metadata
+
+
 # =============================================================================
 # Agent Management API (v5.25.0)
 # =============================================================================

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 Complete installation instructions for all platforms and use cases.
 
-**Version:** v5.33.0
+**Version:** v5.34.0
 
 ---
 
@@ -90,7 +90,7 @@ Open VS Code Settings and search for "loki":
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `loki.provider` | `claude` | Default AI provider |
-| `loki.apiPort` | `9898` | API server port |
+| `loki.apiPort` | `57374` | API server port |
 | `loki.apiHost` | `localhost` | API server host |
 | `loki.autoConnect` | `true` | Auto-connect on activation |
 | `loki.showStatusBar` | `true` | Show status bar item |
@@ -110,10 +110,10 @@ loki start
 ./autonomy/run.sh
 
 # Option C: Direct API server start
-node autonomy/api-server.js
+loki serve
 ```
 
-The extension will automatically connect when it detects the server is running at `localhost:9898`.
+The extension will automatically connect when it detects the server is running at `localhost:57374`.
 
 **Troubleshooting:** If you see "API server is not running" errors, make sure you started the server first using one of the commands above.
 
@@ -579,15 +579,14 @@ Loki Mode uses two network ports for different services:
 
 | Port | Service | Description |
 |------|---------|-------------|
-| **57374** | Dashboard (FastAPI) | Web dashboard UI with real-time monitoring, task board, Completion Council views, memory browser, and log streaming. Served by `dashboard/server.py`. |
-| **9898** | REST API Server | JSON API used by the VS Code extension, CLI tools, and programmatic access. Serves endpoints like `/api/status`, `/api/tasks`, `/api/memory`, etc. |
+| **57374** | Dashboard + API (FastAPI) | Unified server serving both the web dashboard UI (real-time monitoring, task board, Completion Council, memory browser, log streaming) and the REST API (used by VS Code extension, CLI tools, programmatic access). Served by `dashboard/server.py`. |
 
 ### When to Use Which Port
 
 - **Browser access** (dashboard, monitoring): Use port **57374** -- `http://localhost:57374`
-- **API calls** (REST, programmatic): Use port **9898** -- `http://localhost:9898`
-- **VS Code extension**: Connects to API on port **9898** automatically (configurable via `loki.apiPort` setting)
-- **Both ports** are started automatically when you run `loki start` or `./autonomy/run.sh`. No manual configuration is needed.
+- **API calls** (REST, programmatic): Use port **57374** -- `http://localhost:57374`
+- **VS Code extension**: Connects to API on port **57374** automatically (configurable via `loki.apiPort` setting)
+- The server is started automatically when you run `loki start` or `./autonomy/run.sh`. No manual configuration is needed.
 
 ### Port Configuration
 
@@ -595,8 +594,8 @@ Loki Mode uses two network ports for different services:
 # Dashboard port (default: 57374)
 LOKI_DASHBOARD_PORT=57374 loki dashboard start
 
-# API port (default: 9898)
-loki serve --port 9898
+# API port (default: 57374)
+loki serve --port 57374
 ```
 
 ### CORS Configuration

package/docs/TOOL-INTEGRATION.md

@@ -72,7 +72,7 @@ loki memory index
 loki memory retrieve "authentication"
 
 # Manage API server (enables VS Code, dashboard)
-loki serve --port 9898
+loki serve --port 57374
 loki api start
 
 # View dashboard (web UI)

package/docs/dashboard-guide.md

@@ -24,7 +24,7 @@ open http://localhost:57374
 
 The dashboard automatically syncs with Loki Mode when it's running, polling `dashboard-state.json` every 2 seconds.
 
-**Ports:** The dashboard runs on port **57374**. The REST API server runs separately on port **9898**. See [INSTALLATION.md](INSTALLATION.md#ports) for details.
+**Ports:** The dashboard and API run on unified port **57374** (FastAPI serves both). See [INSTALLATION.md](INSTALLATION.md#ports) for details.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "5.33.0",
+  "version": "5.34.0",
   "description": "Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "claude",