loki-mode 6.62.0 → 6.62.1

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 minimal human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v6.62.0
+# Loki Mode v6.62.1
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -267,4 +267,4 @@ The following features are documented in skill modules but not yet fully automat
 | 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 |
 
-**v6.62.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v6.62.1 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-6.62.0
+6.62.1

package/autonomy/hooks/migration-hooks.sh

@@ -31,6 +31,7 @@
 
 set -euo pipefail
 
+# shellcheck disable=SC2034
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Load project-specific hook config if it exists
@@ -38,14 +39,22 @@ load_migration_hook_config() {
     local codebase_path="${1:-.}"
     local config_file="${codebase_path}/.loki/migration-hooks.yaml"
 
-    # Defaults
+    # Defaults (used by other functions in this file; SC2034 disabled for globals-via-function pattern)
+    # shellcheck disable=SC2034
     HOOK_POST_FILE_EDIT_ENABLED=true
+    # shellcheck disable=SC2034
     HOOK_POST_STEP_ENABLED=true
+    # shellcheck disable=SC2034
     HOOK_PRE_PHASE_GATE_ENABLED=true
+    # shellcheck disable=SC2034
     HOOK_ON_AGENT_STOP_ENABLED=true
+    # shellcheck disable=SC2034
     HOOK_POST_FILE_EDIT_ACTION="run_tests"
+    # shellcheck disable=SC2034
     HOOK_POST_FILE_EDIT_ON_FAILURE="block_and_rollback"
+    # shellcheck disable=SC2034
     HOOK_POST_STEP_ON_FAILURE="reject_completion"
+    # shellcheck disable=SC2034
     HOOK_ON_AGENT_STOP_ON_FAILURE="force_continue"
 
     if [[ -f "$config_file" ]] && command -v python3 &>/dev/null; then

package/autonomy/issue-providers.sh

@@ -15,14 +15,19 @@
 #   JSON with normalized fields: provider, number, title, body, labels, author, url, created_at
 #===============================================================================
 
-# Colors (safe to re-source)
+# Colors (safe to re-source; used by scripts that source this file)
+# shellcheck disable=SC2034
 RED='\033[0;31m'
+# shellcheck disable=SC2034
 GREEN='\033[0;32m'
+# shellcheck disable=SC2034
 YELLOW='\033[1;33m'
+# shellcheck disable=SC2034
 CYAN='\033[0;36m'
 NC='\033[0m'
 
-# Supported issue providers
+# Supported issue providers (exported for sourcing scripts)
+# shellcheck disable=SC2034
 ISSUE_PROVIDERS=("github" "gitlab" "jira" "azure_devops")
 
 # Detect issue provider from a URL or reference

package/autonomy/run.sh

@@ -183,7 +183,7 @@ if [[ -z "${LOKI_RUNNING_FROM_TEMP:-}" ]] && [[ "${BASH_SOURCE[0]}" == "${0}" ]]
     cp "${BASH_SOURCE[0]}" "$TEMP_SCRIPT"
     chmod 700 "$TEMP_SCRIPT"
     # BUG-XC-011: Set trap BEFORE exec so the temp file gets cleaned up
-    trap "rm -f '$TEMP_SCRIPT'" EXIT
+    trap 'rm -f "$TEMP_SCRIPT"' EXIT
     export LOKI_RUNNING_FROM_TEMP=1
     export LOKI_ORIGINAL_SCRIPT_DIR="$SCRIPT_DIR"
     export LOKI_ORIGINAL_PROJECT_DIR="$PROJECT_DIR"
@@ -508,6 +508,13 @@ mapping = {
     'model.fast': 'LOKI_MODEL_FAST',
     'notify.slack': 'LOKI_SLACK_WEBHOOK',
     'notify.discord': 'LOKI_DISCORD_WEBHOOK',
+    'provider': 'LOKI_PROVIDER',
+    'issue.provider': 'LOKI_ISSUE_PROVIDER',
+    'blind_validation': 'LOKI_BLIND_VALIDATION',
+    'adversarial_testing': 'LOKI_ADVERSARIAL_TESTING',
+    'spawn_timeout': 'LOKI_SPAWN_TIMEOUT',
+    'spawn_retries': 'LOKI_SPAWN_RETRIES',
+    'budget': 'LOKI_BUDGET_LIMIT',
 }
 for key, env_var in mapping.items():
     # Try nested dict lookup first, then flat key, then underscore variant
@@ -2108,8 +2115,10 @@ create_worktree() {
         git -C "$TARGET_DIR" worktree add "$worktree_path" -b "$branch_name" 2>/dev/null && wt_exit=0 || \
         { git -C "$TARGET_DIR" worktree add "$worktree_path" "$branch_name" 2>/dev/null && wt_exit=0; }
     else
-        # Track main branch
-        git -C "$TARGET_DIR" worktree add "$worktree_path" main 2>/dev/null && wt_exit=0 || \
+        # BUG-PAR-001: Testing/docs worktrees use -b parallel-<stream> main (not bare main checkout)
+        # This avoids "already checked out" errors and keeps each worktree on its own branch
+        git -C "$TARGET_DIR" worktree add "$worktree_path" -b "parallel-${stream_name}" main 2>/dev/null && wt_exit=0 || \
+        { git -C "$TARGET_DIR" worktree add "$worktree_path" "parallel-${stream_name}" 2>/dev/null && wt_exit=0; } || \
         { git -C "$TARGET_DIR" worktree add "$worktree_path" HEAD 2>/dev/null && wt_exit=0; }
     fi
 
@@ -2164,8 +2173,11 @@ remove_worktree() {
 
     # Remove worktree (with safety check for rm -rf)
     git -C "$TARGET_DIR" worktree remove "$worktree_path" --force 2>/dev/null || {
-        # Safety check: only rm -rf if path looks like a worktree (contains .git or is under TARGET_DIR)
-        if [[ -n "$worktree_path" && "$worktree_path" != "/" && "$worktree_path" == "$TARGET_DIR"* ]]; then
+        # BUG-PAR-005: Safety check uses dirname with trailing / to prevent prefix-match false positives
+        # e.g. TARGET_DIR=/foo/bar must not match /foo/bar-other
+        local parent_dir
+        parent_dir="$(dirname "$TARGET_DIR")/"
+        if [[ -n "$worktree_path" && "$worktree_path" != "/" && "$worktree_path" == "${parent_dir}"* ]]; then
             rm -rf "$worktree_path" 2>/dev/null
         else
             log_warn "Skipping unsafe rm -rf for path: $worktree_path"
@@ -2198,7 +2210,11 @@ spawn_worktree_session() {
     done
 
     if [ "$active_count" -ge "$MAX_PARALLEL_SESSIONS" ]; then
-        log_warn "Max parallel sessions reached ($MAX_PARALLEL_SESSIONS). Waiting..."
+        # BUG-PAR-014: Max-sessions rejection queues spawn for retry
+        log_warn "Max parallel sessions reached ($MAX_PARALLEL_SESSIONS). Queuing $stream_name for retry."
+        mkdir -p "${TARGET_DIR:-.}/.loki/signals"
+        echo "{\"stream\":\"$stream_name\",\"task\":\"$(echo "$task_prompt" | head -c 200)\",\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" \
+            > "${TARGET_DIR:-.}/.loki/signals/SPAWN_QUEUED_${stream_name}"
         return 1
     fi
 
@@ -2249,19 +2265,31 @@ spawn_worktree_session() {
 
         # Completion signaling (v6.7.0)
         if [ $_wt_exit -eq 0 ]; then
-            # Commit any uncommitted work
-            git -C "$worktree_path" add -A 2>/dev/null
+            # BUG-PAR-006: git add excludes .env, *.key, *.pem, credentials*
+            git -C "$worktree_path" add -A \
+                ':!.env' ':!*.key' ':!*.pem' ':!credentials*' 2>/dev/null
             git -C "$worktree_path" commit -m "feat($stream_name): worktree work complete" 2>/dev/null || true
-            # Signal merge readiness to main orchestrator
+            # BUG-PAR-008: Signal files written atomically (temp + mv)
             mkdir -p "${TARGET_DIR:-.}/.loki/signals"
-            cat > "${TARGET_DIR:-.}/.loki/signals/MERGE_REQUESTED_${stream_name}" <<EOSIG
+            local _sig_tmp
+            _sig_tmp=$(mktemp "${TARGET_DIR:-.}/.loki/signals/.tmp.XXXXXX") || true
+            cat > "$_sig_tmp" <<EOSIG
 {"stream":"$stream_name","branch":"$(git -C "$worktree_path" branch --show-current 2>/dev/null)","worktree":"$worktree_path","timestamp":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","exit_code":$_wt_exit}
 EOSIG
+            mv "$_sig_tmp" "${TARGET_DIR:-.}/.loki/signals/MERGE_REQUESTED_${stream_name}" 2>/dev/null || \
+                cp "$_sig_tmp" "${TARGET_DIR:-.}/.loki/signals/MERGE_REQUESTED_${stream_name}" 2>/dev/null
+            rm -f "$_sig_tmp" 2>/dev/null
             echo "WORKTREE_COMPLETE: $stream_name" >> "$log_file"
         else
+            # BUG-PAR-008: Signal files written atomically (temp + mv)
             mkdir -p "${TARGET_DIR:-.}/.loki/signals"
+            local _fail_tmp
+            _fail_tmp=$(mktemp "${TARGET_DIR:-.}/.loki/signals/.tmp.XXXXXX") || true
             echo "{\"stream\":\"$stream_name\",\"status\":\"failed\",\"exit_code\":$_wt_exit,\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" \
-                > "${TARGET_DIR:-.}/.loki/signals/WORKTREE_FAILED_${stream_name}"
+                > "$_fail_tmp"
+            mv "$_fail_tmp" "${TARGET_DIR:-.}/.loki/signals/WORKTREE_FAILED_${stream_name}" 2>/dev/null || \
+                cp "$_fail_tmp" "${TARGET_DIR:-.}/.loki/signals/WORKTREE_FAILED_${stream_name}" 2>/dev/null
+            rm -f "$_fail_tmp" 2>/dev/null
         fi
     ) &
 
@@ -2284,9 +2312,12 @@ merge_worktree() {
         return 1
     fi
 
+    # BUG-PAR-013: Signal file parsing falls back to jq when python3 unavailable
     local branch worktree_path
-    branch=$(python3 -c "import json; print(json.load(open('$signal_file'))['branch'])" 2>/dev/null)
-    worktree_path=$(python3 -c "import json; print(json.load(open('$signal_file'))['worktree'])" 2>/dev/null)
+    branch=$(python3 -c "import json; print(json.load(open('$signal_file'))['branch'])" 2>/dev/null) || \
+        branch=$(jq -r '.branch' "$signal_file" 2>/dev/null) || true
+    worktree_path=$(python3 -c "import json; print(json.load(open('$signal_file'))['worktree'])" 2>/dev/null) || \
+        worktree_path=$(jq -r '.worktree' "$signal_file" 2>/dev/null) || true
 
     if [ -z "$branch" ]; then
         log_error "Could not determine branch for: $stream_name"
@@ -2295,9 +2326,16 @@ merge_worktree() {
 
     log_step "Merging worktree: $stream_name (branch: $branch)"
 
-    # Merge into current branch
+    # BUG-PAR-009: Verify git checkout main before merge
     local current_branch
     current_branch=$(git -C "${TARGET_DIR:-.}" branch --show-current 2>/dev/null)
+    if [ "$current_branch" != "main" ]; then
+        log_info "Switching to main before merge (was on: $current_branch)"
+        if ! git -C "${TARGET_DIR:-.}" checkout main 2>/dev/null; then
+            log_error "Failed to checkout main for merge: $stream_name"
+            return 1
+        fi
+    fi
 
     if git -C "${TARGET_DIR:-.}" merge --no-ff "$branch" -m "merge($stream_name): auto-merge from parallel worktree" 2>&1; then
         log_info "Merge successful: $stream_name"
@@ -2440,50 +2478,51 @@ Output ONLY the resolved file content with no conflict markers. No explanations.
 }
 
 # Merge a completed feature branch (with AI conflict resolution)
+# BUG-PAR-011: Not in a subshell -- uses git -C instead of cd
+# BUG-PAR-003: Strips feature- prefix to avoid feature/feature-auth double-prefix
 merge_feature() {
     local feature="$1"
-    local branch="feature/$feature"
+    # BUG-PAR-003: Strip feature- prefix if present to avoid double-prefix (feature/feature-auth)
+    local clean_feature="${feature#feature-}"
+    local branch="feature/$clean_feature"
 
-    log_step "Merging feature: $feature"
+    log_step "Merging feature: $clean_feature"
 
-    (
-        cd "$TARGET_DIR" || exit 1
-
-        # Ensure we're on main
-        git checkout main 2>/dev/null
+    # BUG-PAR-011: Ensure we're on main using git -C (no subshell)
+    git -C "$TARGET_DIR" checkout main 2>/dev/null
 
-        # Attempt merge with no-ff for clear history
-        if git merge "$branch" --no-ff -m "feat: Merge $feature" 2>/dev/null; then
-            log_info "Merged cleanly: $feature"
+    # Attempt merge with no-ff for clear history
+    if git -C "$TARGET_DIR" merge "$branch" --no-ff -m "feat: Merge $clean_feature" 2>/dev/null; then
+        log_info "Merged cleanly: $clean_feature"
+    else
+        # Merge has conflicts - try AI resolution
+        log_warn "Merge conflicts detected - attempting AI resolution"
+
+        if resolve_conflicts_with_ai "$clean_feature"; then
+            # AI resolved conflicts, commit the merge
+            git -C "$TARGET_DIR" commit -m "feat: Merge $clean_feature (AI-resolved conflicts)"
+            audit_agent_action "git_commit" "Committed changes" "merge=$clean_feature,resolution=ai"
+            log_info "Merged with AI conflict resolution: $clean_feature"
         else
-            # Merge has conflicts - try AI resolution
-            log_warn "Merge conflicts detected - attempting AI resolution"
-
-            if resolve_conflicts_with_ai "$feature"; then
-                # AI resolved conflicts, commit the merge
-                git commit -m "feat: Merge $feature (AI-resolved conflicts)"
-                audit_agent_action "git_commit" "Committed changes" "merge=$feature,resolution=ai"
-                log_info "Merged with AI conflict resolution: $feature"
-            else
-                # AI resolution failed, abort merge
-                log_error "AI conflict resolution failed: $feature"
-                git merge --abort 2>/dev/null || true
-                return 1
-            fi
+            # AI resolution failed, abort merge
+            log_error "AI conflict resolution failed: $clean_feature"
+            git -C "$TARGET_DIR" merge --abort 2>/dev/null || true
+            return 1
         fi
+    fi
 
-        # Remove signal
-        rm -f ".loki/signals/MERGE_REQUESTED_$feature"
+    # Remove signal
+    rm -f "$TARGET_DIR/.loki/signals/MERGE_REQUESTED_$feature"
 
-        # Remove worktree
-        remove_worktree "feature-$feature"
+    # Remove worktree
+    remove_worktree "feature-$clean_feature"
 
-        # Delete branch
-        git branch -d "$branch" 2>/dev/null || true
+    # Delete branch
+    git -C "$TARGET_DIR" branch -d "$branch" 2>/dev/null || true
 
-        # Signal for docs update
-        touch ".loki/signals/DOCS_NEEDED"
-    )
+    # Signal for docs update
+    mkdir -p "$TARGET_DIR/.loki/signals"
+    touch "$TARGET_DIR/.loki/signals/DOCS_NEEDED"
 }
 
 # Initialize parallel workflow streams
@@ -2525,7 +2564,9 @@ spawn_feature_stream() {
     local task_description="$2"
 
     # Check worktree limit
-    local worktree_count=$(git -C "$TARGET_DIR" worktree list 2>/dev/null | wc -l)
+    # BUG-PAR-012: Worktree count subtracts 1 for main (git worktree list includes main)
+    local worktree_count_raw=$(git -C "$TARGET_DIR" worktree list 2>/dev/null | wc -l)
+    local worktree_count=$((worktree_count_raw > 0 ? worktree_count_raw - 1 : 0))
     if [ "$worktree_count" -ge "$MAX_WORKTREES" ]; then
         log_warn "Max worktrees reached ($MAX_WORKTREES). Queuing feature: $feature_name"
         return 1
@@ -2594,12 +2635,37 @@ run_parallel_orchestrator() {
 
     # Main orchestrator loop
     local running=true
-    trap 'running=false; cleanup_parallel_streams' INT TERM
+    # BUG-PAR-004: Orchestrator trap handles SIGTERM properly (cleanup + restore global trap + exit)
+    trap 'running=false; cleanup_parallel_streams; trap cleanup INT TERM; exit 0' TERM
+    trap 'running=false; cleanup_parallel_streams' INT
 
     while $running; do
         # Check for merge requests
         check_merge_queue
 
+        # BUG-PAR-014: Retry queued spawns when sessions free up
+        local active_count=0
+        for _qpid in "${WORKTREE_PIDS[@]}"; do
+            if kill -0 "$_qpid" 2>/dev/null; then
+                ((active_count++))
+            fi
+        done
+        if [ "$active_count" -lt "$MAX_PARALLEL_SESSIONS" ]; then
+            for queued_signal in "${TARGET_DIR:-.}"/.loki/signals/SPAWN_QUEUED_*; do
+                [ -f "$queued_signal" ] || continue
+                local queued_stream
+                queued_stream=$(basename "$queued_signal" | sed 's/SPAWN_QUEUED_//')
+                local queued_task=""
+                queued_task=$(python3 -c "import json; print(json.load(open('$queued_signal'))['task'])" 2>/dev/null) || \
+                    queued_task=$(jq -r '.task' "$queued_signal" 2>/dev/null) || true
+                if [ -n "$queued_task" ] && [ -n "${WORKTREE_PATHS[$queued_stream]:-}" ]; then
+                    rm -f "$queued_signal"
+                    spawn_worktree_session "$queued_stream" "$queued_task" && \
+                        log_info "Retried queued spawn: $queued_stream"
+                fi
+            done
+        fi
+
         # Check session health
         for stream in "${!WORKTREE_PIDS[@]}"; do
             local pid="${WORKTREE_PIDS[$stream]}"
@@ -2613,22 +2679,28 @@ run_parallel_orchestrator() {
         local state_file="$TARGET_DIR/.loki/state/parallel-streams.json"
         mkdir -p "$(dirname "$state_file")"
 
+        # BUG-PAR-007: Empty worktree map produces valid JSON
+        local worktree_json=""
+        if [ ${#WORKTREE_PATHS[@]} -gt 0 ]; then
+            worktree_json=$(for stream in "${!WORKTREE_PATHS[@]}"; do
+                local path="${WORKTREE_PATHS[$stream]}"
+                local pid="null"
+                if [ -n "${WORKTREE_PIDS[$stream]+x}" ]; then
+                    pid="${WORKTREE_PIDS[$stream]}"
+                fi
+                local status="stopped"
+                if [ "$pid" != "null" ] && kill -0 "$pid" 2>/dev/null; then
+                    status="running"
+                fi
+                echo "    \"$stream\": {\"path\": \"$path\", \"pid\": $pid, \"status\": \"$status\"},"
+            done | sed '$ s/,$//')
+        fi
+
         cat > "$state_file" << EOF
 {
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "worktrees": {
-$(for stream in "${!WORKTREE_PATHS[@]}"; do
-    local path="${WORKTREE_PATHS[$stream]}"
-    local pid="null"
-    if [ -n "${WORKTREE_PIDS[$stream]+x}" ]; then
-        pid="${WORKTREE_PIDS[$stream]}"
-    fi
-    local status="stopped"
-    if [ "$pid" != "null" ] && kill -0 "$pid" 2>/dev/null; then
-        status="running"
-    fi
-    echo "    \"$stream\": {\"path\": \"$path\", \"pid\": $pid, \"status\": \"$status\"},"
-done | sed '$ s/,$//')
+${worktree_json}
   },
   "active_sessions": ${#WORKTREE_PIDS[@]},
   "max_sessions": $MAX_PARALLEL_SESSIONS

package/autonomy/sandbox.sh

@@ -904,7 +904,9 @@ except: pass
             local container_path="${parts[1]}"
             local mode="${parts[2]:-ro}"
 
-            # Safe tilde expansion (no eval)
+            # Safe tilde expansion (no eval) - SC2088 disabled: tilde is intentionally
+            # treated as a literal string here for safe expansion without eval
+            # shellcheck disable=SC2088
             if [[ "$host_path" == "~/"* ]]; then
                 host_path="$HOME/${host_path#\~/}"
             elif [[ "$host_path" == "~" ]]; then
@@ -1121,7 +1123,8 @@ start_sandbox() {
             local c_container="${mount_parts[1]:-}"
             local c_mode="${mount_parts[2]:-ro}"
             if [[ -n "$c_host" ]] && [[ -n "$c_container" ]]; then
-                # Safe tilde expansion (no eval)
+                # Safe tilde expansion (no eval) - SC2088 disabled: intentional literal match
+                # shellcheck disable=SC2088
                 if [[ "$c_host" == "~/"* ]]; then
                     c_host="$HOME/${c_host#\~/}"
                 elif [[ "$c_host" == "~" ]]; then

package/dashboard/__init__.py

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

package/docs/INSTALLATION.md

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

package/mcp/__init__.py

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

package/memory/engine.py

@@ -360,6 +360,7 @@ class MemoryEngine:
         pattern_id = self.storage.save_pattern(pattern)
 
         # Update index
+        pattern_dict = pattern.model_dump() if hasattr(pattern, "model_dump") else pattern.__dict__
         self._update_index_with_pattern(pattern_dict)
 
         return pattern_id

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "6.62.0",
+  "version": "6.62.1",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "agent",

package/state/manager.py

@@ -22,6 +22,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Set, Tuple, Union
 from enum import Enum
 from contextlib import contextmanager
+import copy
 import uuid
 import glob as glob_module
 
@@ -102,11 +103,11 @@ class VersionVector:
     def concurrent_with(self, other: "VersionVector") -> bool:
         """Check if two vectors are concurrent (neither dominates).
 
-        Per causality rules, identical vectors are concurrent (happened
-        independently with the same knowledge).
+        Identical vectors represent the same causal point, NOT
+        concurrent operations, so they return False (BUG-ST-006).
         """
         if self.versions == other.versions:
-            return True
+            return False
         return not self.dominates(other) and not other.dominates(self)
 
     def to_dict(self) -> Dict[str, int]:
@@ -796,6 +797,9 @@ class StateManager:
         """
         Merge updates into existing state.
 
+        Holds a file lock across the entire read-modify-write to prevent
+        lost updates from concurrent callers (BUG-ST-002).
+
         Args:
             file_ref: File reference
             updates: Dictionary of updates to merge
@@ -804,9 +808,57 @@ class StateManager:
         Returns:
             StateChange object
         """
-        current = self.get_state(file_ref, default={})
-        merged = {**current, **updates}
-        return self.set_state(file_ref, merged, source)
+        path = self._resolve_path(file_ref)
+
+        with self._file_lock(path, exclusive=True):
+            # Read current state under the lock (bypass cache to get
+            # the true on-disk value while we hold the exclusive lock)
+            old_value = None
+            if path.exists():
+                try:
+                    with open(path, "r") as f:
+                        old_value = json.load(f)
+                except (json.JSONDecodeError, IOError):
+                    old_value = None
+
+            current = old_value if old_value is not None else {}
+            merged = {**current, **updates}
+            change_type = "create" if old_value is None else "update"
+
+            # Save version before writing new data (SYN-015)
+            if self.enable_versioning and old_value is not None:
+                self._save_version(file_ref, old_value, source, change_type)
+
+            # Write atomically (temp file + rename) while still under lock
+            path.parent.mkdir(parents=True, exist_ok=True)
+            fd, temp_path = tempfile.mkstemp(
+                dir=path.parent, prefix=".tmp_", suffix=".json"
+            )
+            try:
+                with os.fdopen(fd, "w") as f:
+                    json.dump(merged, f, indent=2, default=str)
+                shutil.move(temp_path, path)
+            except Exception:
+                if os.path.exists(temp_path):
+                    os.unlink(temp_path)
+                raise
+
+            # Update cache
+            self._put_in_cache(path, merged)
+
+        # Create change object
+        change = StateChange(
+            file_path=str(path.relative_to(self.loki_dir)),
+            old_value=old_value,
+            new_value=merged,
+            change_type=change_type,
+            source=source
+        )
+
+        # Broadcast change
+        self._broadcast(change)
+
+        return change
 
     def delete_state(
         self,
@@ -1147,16 +1199,38 @@ class StateManager:
         return states
 
     def refresh_cache(self) -> None:
-        """Refresh all cached entries from disk."""
+        """Refresh all cached entries from disk.
+
+        Collects paths under _cache_lock, releases it, reads files
+        (which acquire file locks), then re-acquires _cache_lock to
+        update entries. This avoids an ABBA deadlock between the
+        cache lock and file locks (BUG-ST-001).
+        """
+        # Step 1: collect paths under the cache lock
+        with self._cache_lock:
+            paths_to_refresh = list(self._cache.keys())
+
+        # Step 2: read files WITHOUT holding _cache_lock
+        refreshed: dict = {}
+        gone: list = []
+        for path_str in paths_to_refresh:
+            path = Path(path_str)
+            if path.exists():
+                data = self._read_file(path)
+                if data:
+                    refreshed[path_str] = data
+            else:
+                gone.append(path_str)
+
+        # Step 3: re-acquire _cache_lock and update entries
         with self._cache_lock:
-            for path_str in list(self._cache.keys()):
+            for path_str, data in refreshed.items():
                 path = Path(path_str)
-                if path.exists():
-                    data = self._read_file(path)
-                    if data:
-                        self._put_in_cache(path, data)
-                else:
-                    del self._cache[path_str]
+                data_hash = self._compute_hash(data)
+                mtime = path.stat().st_mtime if path.exists() else 0
+                self._cache[path_str] = (data, data_hash, mtime)
+            for path_str in gone:
+                self._cache.pop(path_str, None)
 
     # -------------------------------------------------------------------------
     # Optimistic Updates (SYN-014)
@@ -1231,8 +1305,9 @@ class StateManager:
             self._pending_updates[path_str] = []
         self._pending_updates[path_str].append(pending)
 
-        # Apply optimistically to local state
-        current_state = self.get_state(file_ref, default={})
+        # Apply optimistically to local state -- deepcopy to avoid
+        # mutating the cached dict in-place (BUG-ST-011)
+        current_state = copy.deepcopy(self.get_state(file_ref, default={}))
         current_state[key] = value
         current_state["_version_vector"] = version_vector.to_dict()
         current_state["_last_source"] = source
@@ -1394,14 +1469,23 @@ class StateManager:
             return merged
 
         elif isinstance(local, list) and isinstance(remote, list):
-            # Concatenate and deduplicate (preserving order)
+            # Concatenate and deduplicate (preserving order).
+            # Use try/except to handle unhashable types gracefully
+            # by falling back to JSON serialization (BUG-ST-013).
             seen = set()
             merged = []
             for item in local + remote:
-                item_key = json.dumps(item, sort_keys=True, default=str) if isinstance(item, (dict, list)) else item
-                if item_key not in seen:
-                    seen.add(item_key)
-                    merged.append(item)
+                try:
+                    item_key = json.dumps(item, sort_keys=True, default=str) if isinstance(item, (dict, list)) else item
+                    if item_key not in seen:
+                        seen.add(item_key)
+                        merged.append(item)
+                except TypeError:
+                    # Unhashable type -- fall back to JSON string as key
+                    item_key = json.dumps(item, sort_keys=True, default=str)
+                    if item_key not in seen:
+                        seen.add(item_key)
+                        merged.append(item)
             return merged
 
         else:
@@ -1598,23 +1682,27 @@ class StateManager:
         return version
 
     def _cleanup_old_versions(self, file_ref: Union[str, ManagedFile]) -> None:
-        """Remove versions beyond the retention limit."""
+        """Remove versions beyond the retention limit.
+
+        Only considers files with purely numeric stems so that orphan
+        temp files (e.g. .tmp_xxx.json) are not counted toward the
+        retention limit (BUG-ST-010).
+        """
         history_dir = self._get_history_dir(file_ref)
         if not history_dir.exists():
             return
 
         version_files = glob_module.glob(str(history_dir / "*.json"))
-        if len(version_files) <= self.version_retention:
-            return
 
-        # Sort by version number and remove oldest
+        # Filter to numeric stems only (skip temp/orphan files)
         version_nums = []
         for vf in version_files:
-            try:
-                version_num = int(Path(vf).stem)
-                version_nums.append((version_num, vf))
-            except ValueError:
-                pass
+            stem = Path(vf).stem
+            if stem.isdigit():
+                version_nums.append((int(stem), vf))
+
+        if len(version_nums) <= self.version_retention:
+            return
 
         version_nums.sort(key=lambda x: x[0])
         to_remove = version_nums[:-self.version_retention]
@@ -1777,17 +1865,24 @@ class StateManager:
 
 # Singleton instance for convenience
 _default_manager: Optional[StateManager] = None
+_default_manager_lock = threading.Lock()
 
 
 def get_state_manager(
     loki_dir: Optional[Union[str, Path]] = None,
     **kwargs
 ) -> StateManager:
-    """Get the default state manager instance."""
+    """Get the default state manager instance.
+
+    Uses double-checked locking to avoid a race where two threads
+    could both create a StateManager simultaneously (BUG-ST-007).
+    """
     global _default_manager
 
     if _default_manager is None:
-        _default_manager = StateManager(loki_dir, **kwargs)
+        with _default_manager_lock:
+            if _default_manager is None:
+                _default_manager = StateManager(loki_dir, **kwargs)
 
     return _default_manager