superlocalmemory 3.8.3 → 3.8.6

package/src/superlocalmemory/cli/ingest_cmd.py

@@ -281,15 +281,25 @@ def _write_tool_events(events: list[dict]) -> int:
 
     v3.4.10: Preserves input_summary, output_summary, and project_path
     from enriched sources (ECC observations, enriched hook).
+
+    Concurrency note
+    ----------------
+    ``slm ingest`` is a SEPARATE OS process — the daemon's threading.RLock
+    write-lock cannot help here.  PRAGMA busy_timeout is the only cross-process
+    lever: it makes SQLite WAIT for the single writer (daemon / hook) to finish
+    instead of immediately raising SQLITE_BUSY.  The ``timeout`` kwarg to
+    sqlite3.connect is the Python-level retry budget (same duration).
     """
     db_path = Path(MEMORY_DB)
     if not db_path.exists():
         return 0
 
-    conn = sqlite3.connect(str(db_path), timeout=10)
+    _busy_ms = 10_000
+    conn = sqlite3.connect(str(db_path), timeout=_busy_ms / 1000.0)
     count = 0
 
     try:
+        conn.execute(f"PRAGMA busy_timeout={_busy_ms}")
         for ev in events:
             try:
                 conn.execute(

package/src/superlocalmemory/cli/main.py

@@ -252,6 +252,36 @@ def main() -> None:
         "--dry-run", action="store_true", dest="dry_run", default=False,
         help="Show what would be written without making changes",
     )
+    # Workstream C — transport flexibility (3.8.4)
+    connect_p.add_argument(
+        "--transport",
+        choices=["stdio", "http", "http-mcp-remote"],
+        default="stdio",
+        dest="transport",
+        help=(
+            "MCP transport to write into the IDE config. "
+            "stdio (default, zero regression) | "
+            "http (native Streamable-HTTP, requires SLM daemon) | "
+            "http-mcp-remote (stdio bridge via mcp-remote for stdio-only clients)"
+        ),
+    )
+    connect_p.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        dest="daemon_port",
+        help="SLM daemon port for http/http-mcp-remote transport (default: 8765)",
+    )
+    connect_p.add_argument(
+        "--verify",
+        action="store_true",
+        default=False,
+        dest="verify",
+        help=(
+            "After writing the config, probe the daemon health endpoint to confirm "
+            "the transport is reachable (only meaningful for --transport http)"
+        ),
+    )
 
     migrate_p = sub.add_parser("migrate", help="Migrate data from V2 to V3 schema")
     migrate_p.add_argument(

package/src/superlocalmemory/cli/pending_store.py

@@ -40,6 +40,13 @@ _MAX_RETRIES = 3
 _STUCK_DAYS = 7
 _MAX_RETRY_DELAY_SECONDS = 3600
 
+# Fix F: hard cap on pending.db retries. After this many failed attempts the
+# item transitions to status='dead_letter' (next_retry_at=NULL) so it is
+# permanently excluded from the work queue.  Value chosen to survive transient
+# engine unavailability (12h at 30-min drain intervals) while still providing
+# a definitive signal for genuinely poisoned content.
+_MAX_RETRY_COUNT: int = 20
+
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS pending_memories (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -180,9 +187,17 @@ def mark_done(row_id: int, base_dir: Path | None = None) -> None:
 def mark_failed(row_id: int, error: str, base_dir: Path | None = None) -> None:
     """Mark a pending memory as failed with error message.
 
-    Unprocessed evidence is never deleted or terminally hidden. Failures stay
-    pending with bounded exponential backoff; M018 idempotency makes repeated
-    replay safe once the canonical operation has been created.
+    Fix F: when the retry counter reaches _MAX_RETRY_COUNT the item transitions
+    to ``status='dead_letter'`` with ``next_retry_at=NULL``.  Dead-lettered
+    items are excluded from the work queue (``get_pending`` filters
+    ``status='pending'``) and are not resurrected by the startup
+    ``UPDATE…WHERE status='failed'`` sweep (which targets only 'failed', not
+    'dead_letter').  This gives operators a stable, inspectable record of
+    genuinely poisoned content instead of an infinite retry loop.
+
+    Below the cap, failures stay pending with bounded exponential backoff;
+    M018 idempotency makes repeated replay safe once the canonical operation
+    has been created.
     """
     conn = _get_db(base_dir)
     try:
@@ -193,17 +208,27 @@ def mark_failed(row_id: int, error: str, base_dir: Path | None = None) -> None:
         if row is None:
             return
         next_count = int(row[0] or 0) + 1
-        delay = 0 if next_count == 1 else min(
-            2 ** min(next_count - 1, 12),
-            _MAX_RETRY_DELAY_SECONDS,
-        )
-        conn.execute(
-            "UPDATE pending_memories SET error = ?, "
-            "retry_count = retry_count + 1, "
-            "status = 'pending', next_retry_at = ? "
-            "WHERE id = ?",
-            (error, time.time() + delay, row_id),
-        )
+        if next_count >= _MAX_RETRY_COUNT:
+            # Fix F: permanently exclude from work queue — dead-letter.
+            conn.execute(
+                "UPDATE pending_memories SET error = ?, "
+                "retry_count = retry_count + 1, "
+                "status = 'dead_letter', next_retry_at = NULL "
+                "WHERE id = ?",
+                (error, row_id),
+            )
+        else:
+            delay = 0 if next_count == 1 else min(
+                2 ** min(next_count - 1, 12),
+                _MAX_RETRY_DELAY_SECONDS,
+            )
+            conn.execute(
+                "UPDATE pending_memories SET error = ?, "
+                "retry_count = retry_count + 1, "
+                "status = 'pending', next_retry_at = ? "
+                "WHERE id = ?",
+                (error, time.time() + delay, row_id),
+            )
         conn.commit()
     finally:
         conn.close()

package/src/superlocalmemory/core/backend_orchestrator.py

@@ -100,6 +100,11 @@ class BackendOrchestrator:
                 "Scale Engine remains on Local Core (state=%s)",
                 getattr(self._config, "scale_engine_state", "local_core"),
             )
+            # v3.8.5: schedule a background check that auto-promotes to
+            # Cozo+LanceDB only once the DB is large enough that they beat the
+            # SQLite graph.  A no-op (and never even starts the build) for the
+            # vast majority of installs, which sit far below the threshold.
+            self._maybe_schedule_auto_promote()
             return
 
         # 3. Initialize CozoDB if available
@@ -129,6 +134,94 @@ class BackendOrchestrator:
                      "active" if self._cozo and self._cozo_status() == "active" else "off",
                      "active" if self._lancedb and self._lancedb_status() == "active" else "off")
 
+    def _maybe_schedule_auto_promote(self) -> None:
+        """Schedule a delayed, one-shot scale auto-promote check (v3.8.5).
+
+        Fires well after boot warmup so it never competes for CPU / the write
+        lock during the startup window — the daemon keeps serving canonical
+        SQLite throughout.  A no-op (never even starts the build) unless
+        auto-promotion is enabled AND the DB has grown past the threshold where
+        a graph DB actually beats the well-indexed SQLite graph.
+        """
+        import os
+        import threading
+
+        cfg = self._config
+        if not getattr(cfg, "scale_auto_promote_enabled", True):
+            return
+        if getattr(cfg, "scale_engine_state", "local_core") != "local_core":
+            return
+        try:
+            delay = float(os.environ.get("SLM_AUTO_PROMOTE_DELAY_S", "300"))
+        except (TypeError, ValueError):
+            delay = 300.0
+        timer = threading.Timer(delay, self._auto_promote_if_at_scale)
+        timer.daemon = True
+        timer.start()
+
+    def _count_default_edges(self) -> int:
+        """graph_edges count for the default profile (fail-soft → 0)."""
+        try:
+            rows = self._db.execute(
+                "SELECT COUNT(*) AS c FROM graph_edges WHERE profile_id = 'default'"
+            )
+            return int(rows[0]["c"]) if rows else 0
+        except Exception:
+            return 0
+
+    def _auto_promote_if_at_scale(self) -> None:
+        """Build + promote the Cozo/Lance projection iff the DB is at scale.
+
+        Uses the SAME staged parity gate as the manual CLI path
+        (prepare → verify → promote).  Any failure leaves canonical SQLite
+        selected — the projection is derived data, never the source of truth.
+        The promoted backends only serve after the next daemon restart, so this
+        logs a clear, actionable message rather than swapping under a live
+        process.
+        """
+        try:
+            import os
+
+            cfg = self._config
+            if getattr(cfg, "scale_engine_state", "local_core") != "local_core":
+                return
+            threshold = int(
+                os.environ.get("SLM_AUTO_PROMOTE_MIN_EDGES", "")
+                or getattr(cfg, "scale_auto_promote_min_edges", 1_000_000)
+            )
+            edges = self._count_default_edges()
+            if edges < threshold:
+                logger.info(
+                    "Scale auto-promote: %d edges < threshold %d — Local Core "
+                    "(SQLite) stays optimal; no projection built.",
+                    edges, threshold,
+                )
+                return
+            logger.info(
+                "Scale auto-promote: %d edges >= threshold %d — building "
+                "Cozo+LanceDB projection in the background (SQLite keeps serving).",
+                edges, threshold,
+            )
+            from superlocalmemory.core.scale_engine import ScaleEngineManager
+
+            mgr = ScaleEngineManager(cfg, profile_id="default")
+            prepared = mgr.prepare()
+            stage_id = prepared.get("stage_id")
+            mgr.verify(stage_id)
+            mgr.promote(stage_id)
+            logger.warning(
+                "Scale Engine AUTO-PROMOTED to Cozo+LanceDB at %d edges. RESTART "
+                "the daemon (`slm restart`) to activate the backends; until then "
+                "it keeps serving canonical SQLite.",
+                edges,
+            )
+        except Exception as exc:
+            # Derived-data failure must never take down Local Core.
+            logger.warning(
+                "Scale auto-promote skipped — staying on Local Core / SQLite: %s",
+                exc,
+            )
+
     def _recover_interrupted_scale_promotion(self) -> None:
         """Repair an interrupted promotion; never auto-mutate a legacy root."""
         try:

package/src/superlocalmemory/core/component_registry.py

@@ -265,8 +265,10 @@ def probe_reranker_model(config: Any = None) -> Component:
         auto_fixable=enabled,
         fix_cmd="slm doctor --fix",
     )
-    if not enabled and comp.status == STATUS_MISSING:
-        # Not enabled → absent is expected, not a problem.
+    if not enabled:
+        # A cached reranker is still inactive when the operator disabled the
+        # channel. The dashboard must describe configured runtime state, not
+        # machine-specific HuggingFace-cache state.
         return replace(comp, status=STATUS_OK,
                        detail="disabled (retrieval.use_cross_encoder=false)",
                        fix_cmd="", auto_fixable=False)

package/src/superlocalmemory/core/config.py

@@ -960,6 +960,29 @@ class HealthConfig:
     enable_structured_logging: bool = True
 
 
+# ---------------------------------------------------------------------------
+# Graph Pruning Config (Workstream G — #84)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class GraphPruningConfig:
+    """Graph thinning parameters.  Exposed via dashboard + CLI.
+
+    Defaults reproduce the previous hard-coded behaviour so existing
+    deployments see zero behavioural change after upgrade.
+    """
+
+    #: Maximum in- or out-degree per node.  Maps to the legacy module-level
+    #: ``_MAX_DEGREE_PER_NODE = 100`` in graph_pruner.py.
+    max_degree_per_node: int = 100
+    #: Discard edges with weight strictly below this floor.
+    #: 0.0 = no floor (current behaviour, always-safe default).
+    min_edge_weight: float = 0.0
+    #: Master kill-switch for all graph pruning.  ``False`` skips the entire
+    #: prune step (useful for debugging graph bloat).
+    enabled: bool = True
+
+
 # ---------------------------------------------------------------------------
 # Master Config
 # ---------------------------------------------------------------------------
@@ -1008,8 +1031,19 @@ class SLMConfig:
     # Scale Engine is installed separately from activation.  Existing roots
     # stay on SQLite until a staged parity check promotes these projections.
     scale_engine_state: str = "local_core"  # local_core | prepared | verified | promoted
+    # v3.8.5: auto-promote Cozo+LanceDB when a DB grows past the scale at which
+    # they actually help.  Below the threshold the well-indexed SQLite graph is
+    # faster (measured ~1.7ms/traversal at 208K edges), so normal installs stay
+    # on Local Core and never pay the projection/migration cost.  The threshold
+    # is deliberately high: the graph DB win appears at millions of edges, not
+    # hundreds of thousands.  Auto-promotion is background, uses the same staged
+    # parity gate as the manual path, and falls back to SQLite on any failure.
+    scale_auto_promote_enabled: bool = True
+    scale_auto_promote_min_edges: int = 1_000_000
     evolution: EvolutionConfig = field(default_factory=EvolutionConfig)
     health: HealthConfig = field(default_factory=HealthConfig)
+    # v3.8.4-G: Graph thinning parameters (#84)
+    graph_pruning: GraphPruningConfig = field(default_factory=GraphPruningConfig)
 
     # v3.4.3: Daemon configuration
     daemon_idle_timeout: int = 0       # 0 = 24/7 (no auto-kill). >0 = seconds before auto-kill.
@@ -1122,6 +1156,15 @@ class SLMConfig:
             state if state in {"local_core", "prepared", "verified", "promoted"}
             else "local_core"
         )
+        config.scale_auto_promote_enabled = bool(
+            data.get("scale_auto_promote_enabled", True)
+        )
+        try:
+            config.scale_auto_promote_min_edges = int(
+                data.get("scale_auto_promote_min_edges", 1_000_000)
+            )
+        except (TypeError, ValueError):
+            config.scale_auto_promote_min_edges = 1_000_000
 
         # V3.3 config fields (additive — defaults work if missing from JSON)
         fg = data.get("forgetting", {})
@@ -1174,6 +1217,31 @@ class SLMConfig:
                 if k in HealthConfig.__dataclass_fields__
             })
 
+        # v3.8.4-G: Graph pruning config (#84) — additive, no migration needed.
+        # Old configs without this section silently fall back to GraphPruningConfig()
+        # defaults, which reproduce the existing _MAX_DEGREE_PER_NODE=100 behaviour.
+        gp_raw = data.get("graph_pruning", {})
+        if gp_raw:
+            try:
+                gp_kwargs = {
+                    k: v for k, v in gp_raw.items()
+                    if k in GraphPruningConfig.__dataclass_fields__
+                }
+                gp = GraphPruningConfig(**gp_kwargs)
+                # Validate and clamp out-of-range values
+                max_deg = gp.max_degree_per_node if gp.max_degree_per_node >= 1 else 100
+                min_w = max(0.0, min(1.0, gp.min_edge_weight))
+                config.graph_pruning = GraphPruningConfig(
+                    max_degree_per_node=max_deg,
+                    min_edge_weight=min_w,
+                    enabled=gp.enabled,
+                )
+            except (ValueError, TypeError) as exc:
+                logger.warning(
+                    "graph_pruning config invalid (%s) — using defaults", exc
+                )
+                config.graph_pruning = GraphPruningConfig()
+
         # V3.4.65: Injection config (additive — defaults if missing from JSON)
         inj = data.get("injection", {}) or {}
         config.injection = InjectionConfig(
@@ -1271,6 +1339,8 @@ class SLMConfig:
             "graph_backend": self.graph_backend,
             "vector_backend": self.vector_backend,
             "scale_engine_state": self.scale_engine_state,
+            "scale_auto_promote_enabled": self.scale_auto_promote_enabled,
+            "scale_auto_promote_min_edges": self.scale_auto_promote_min_edges,
             "base_dir": str(self.base_dir),  # V3.5.9: persist so load() can restore custom paths
             "llm": {
                 "provider": self.llm.provider,
@@ -1329,6 +1399,14 @@ class SLMConfig:
         # Multi-scope memory: behaviour defaults
         data["scope"] = self.scope.as_dict()
 
+        # v3.8.4-G: Persist graph pruning config (#84).
+        # Always written — additive key, never overwrites unrelated sections.
+        data["graph_pruning"] = {
+            "max_degree_per_node": self.graph_pruning.max_degree_per_node,
+            "min_edge_weight": self.graph_pruning.min_edge_weight,
+            "enabled": self.graph_pruning.enabled,
+        }
+
         # Preserve existing V3.3 config sections that aren't in for_mode()
         for key in ("forgetting", "quantization", "sagq", "embedding_signature", "auto_invoke"):
             if key in existing:

package/src/superlocalmemory/core/consolidation_engine.py

@@ -708,93 +708,99 @@ class ConsolidationEngine:
         Uses 'custom' category because the soft_prompt_templates CHECK
         constraint does not include 'skill_evolution'. The content is
         prefixed with [SKILL_EVOLUTION] for easy filtering.
-        """
-        import sqlite3 as _sqlite3
 
-        db_path = str(self._db.db_path)
+        Concurrency fix (v3.8.4): all writes routed through memory_write()
+        so the process write lock (get_write_lock) serialises in-process
+        writers and proper busy_timeout handles cross-process races.
+        No slow ops are held inside the write lock — this method has none.
+        """
+        from superlocalmemory.storage.memory_write import memory_read, memory_write
 
-        conn = _sqlite3.connect(db_path, timeout=10)
-        conn.row_factory = _sqlite3.Row
+        db_path = self._db.db_path
 
-        # Fetch promoted evolutions
+        # Phase 1: read-only fetch — does NOT hold the write lock.
         try:
-            promoted_rows = conn.execute(
-                "SELECT id, skill_name, parent_skill_id, evolution_type, "
-                "mutation_summary, created_at "
-                "FROM skill_evolution_log "
-                "WHERE status = 'promoted' "
-                "ORDER BY created_at DESC LIMIT 20",
-            ).fetchall()
-        except _sqlite3.OperationalError:
+            with memory_read(db_path) as rconn:
+                promoted_rows = [
+                    dict(r)
+                    for r in rconn.execute(
+                        "SELECT id, skill_name, parent_skill_id, evolution_type, "
+                        "mutation_summary, created_at "
+                        "FROM skill_evolution_log "
+                        "WHERE status = 'promoted' "
+                        "ORDER BY created_at DESC LIMIT 20",
+                    ).fetchall()
+                ]
+        except Exception:
             # Table may not exist yet
-            conn.close()
             return {"created": 0, "message": "skill_evolution_log table not found"}
 
-        created_count = 0
+        if not promoted_rows:
+            return {"promoted_skills_found": 0, "soft_prompts_created": 0}
+
         now = datetime.now(timezone.utc).isoformat()
+        created_count = 0
 
-        for row in promoted_rows:
-            r = dict(row)
-            skill_name = r["skill_name"]
-            parent = r.get("parent_skill_id") or skill_name
-            evo_type = r["evolution_type"]
-            summary = r.get("mutation_summary", "")
-            evo_id = r["id"]
-
-            # Build prompt content
-            content = (
-                f"[SKILL_EVOLUTION] Evolved skill: '{skill_name}' "
-                f"({'replaces' if evo_type == 'fix' else 'extends'} '{parent}' "
-                f"via {evo_type}). {summary}. "
-                f"Use the evolved version for better results."
-            )
+        # Phase 2: short write transaction — hold the write lock for the
+        # INSERT/UPDATE loop only (pure SQL, no network / embed calls).
+        with memory_write(db_path) as conn:
+            for r in promoted_rows:
+                skill_name = r["skill_name"]
+                parent = r.get("parent_skill_id") or skill_name
+                evo_type = r["evolution_type"]
+                summary_txt = r.get("mutation_summary", "")
+                evo_id = r["id"]
+
+                content = (
+                    f"[SKILL_EVOLUTION] Evolved skill: '{skill_name}' "
+                    f"({'replaces' if evo_type == 'fix' else 'extends'} '{parent}' "
+                    f"via {evo_type}). {summary_txt}. "
+                    f"Use the evolved version for better results."
+                )
+                prompt_id = f"evo-{evo_id}"
 
-            # Use a deterministic prompt_id based on the evolution record
-            prompt_id = f"evo-{evo_id}"
+                existing = conn.execute(
+                    "SELECT prompt_id FROM soft_prompt_templates WHERE prompt_id = ?",
+                    (prompt_id,),
+                ).fetchone()
 
-            # Check if prompt already exists
-            existing = conn.execute(
-                "SELECT prompt_id FROM soft_prompt_templates WHERE prompt_id = ?",
-                (prompt_id,),
-            ).fetchone()
+                if existing:
+                    # M-REPLACE: Update existing record instead of INSERT OR REPLACE
+                    # to avoid silently dropping columns with defaults.
+                    try:
+                        conn.execute(
+                            "UPDATE soft_prompt_templates "
+                            "SET content = ?, updated_at = ? "
+                            "WHERE prompt_id = ?",
+                            (content, now, prompt_id),
+                        )
+                    except Exception as upd_exc:
+                        logger.debug(
+                            "Failed to update soft prompt %s: %s", prompt_id, upd_exc
+                        )
+                    continue
 
-            if existing:
-                # M-REPLACE: Update existing record instead of INSERT OR REPLACE
-                # to avoid silently dropping columns with defaults
                 try:
-                    conn.execute(
-                        "UPDATE soft_prompt_templates "
-                        "SET content = ?, updated_at = ? "
-                        "WHERE prompt_id = ?",
-                        (content, now, prompt_id),
+                    cur = conn.execute(
+                        "INSERT OR IGNORE INTO soft_prompt_templates "
+                        "(prompt_id, profile_id, category, content, source_pattern_ids, "
+                        " confidence, effectiveness, token_count, retention_score, "
+                        " active, version, created_at, updated_at) "
+                        "VALUES (?, ?, 'custom', ?, ?, 0.8, 0.5, ?, 1.0, 1, 1, ?, ?)",
+                        (
+                            prompt_id, profile_id, content,
+                            json.dumps([evo_id]),
+                            len(content.split()),
+                            now, now,
+                        ),
+                    )
+                    if cur.rowcount > 0:
+                        created_count += 1
+                except Exception as ins_exc:
+                    # Unique constraint on (profile_id, category) WHERE active=1
+                    logger.debug(
+                        "Skipping soft prompt for %s: %s", skill_name, ins_exc
                     )
-                except _sqlite3.OperationalError as upd_exc:
-                    logger.debug("Failed to update soft prompt %s: %s", prompt_id, upd_exc)
-                continue
-
-            try:
-                conn.execute(
-                    "INSERT OR IGNORE INTO soft_prompt_templates "
-                    "(prompt_id, profile_id, category, content, source_pattern_ids, "
-                    " confidence, effectiveness, token_count, retention_score, "
-                    " active, version, created_at, updated_at) "
-                    "VALUES (?, ?, 'custom', ?, ?, 0.8, 0.5, ?, 1.0, 1, 1, ?, ?)",
-                    (prompt_id, profile_id, content,
-                     json.dumps([evo_id]),
-                     len(content.split()),  # Rough token estimate
-                     now, now),
-                )
-                if conn.total_changes:
-                    created_count += 1
-            except _sqlite3.IntegrityError:
-                # Unique constraint on (profile_id, category) WHERE active=1
-                logger.debug(
-                    "Skipping soft prompt for %s: unique constraint on active custom",
-                    skill_name,
-                )
-
-        conn.commit()
-        conn.close()
 
         return {
             "promoted_skills_found": len(promoted_rows),

package/src/superlocalmemory/core/embeddings.py

@@ -250,11 +250,38 @@ class EmbeddingService:
     def dimension(self) -> int:
         return self._config.dimension
 
-    def unload(self) -> None:
-        """Kill the worker subprocess to free all memory."""
-        with self._lock:
+    def unload(self, timeout: float = 1.0) -> bool:
+        """Release the worker without blocking daemon shutdown on an embed call.
+
+        An in-flight request owns ``_lock`` while it waits for the worker's
+        response.  Shutdown must not wait behind a wedged response: callers
+        can continue teardown and the worker process will be handled by the
+        process supervisor if necessary.
+        """
+        if not self._lock.acquire(timeout=max(0.0, timeout)):
+            logger.warning("EmbeddingService: unload skipped; embed worker is busy")
+            return False
+        try:
             self._kill_worker()
             logger.info("EmbeddingService: worker killed (idle timeout)")
+            return True
+        finally:
+            self._lock.release()
+
+    def shutdown(self, timeout: float = 1.0) -> None:
+        """Force bounded process teardown even when an embed call owns the lock.
+
+        Shutdown is stronger than the idle-time ``unload`` operation.  Once
+        the engine is closing, no new request may use this service, so it is
+        safe to detach and terminate a wedged child without waiting behind the
+        request lock.
+        """
+        acquired = self._lock.acquire(timeout=max(0.0, timeout))
+        try:
+            self._kill_worker(timeout=min(max(0.0, timeout), 1.0))
+        finally:
+            if acquired:
+                self._lock.release()
 
     # ------------------------------------------------------------------
     # Public API
@@ -596,7 +623,7 @@ class EmbeddingService:
             self._available = False
             self._worker_proc = None
 
-    def _kill_worker(self) -> None:
+    def _kill_worker(self, timeout: float = 3.0) -> None:
         """Terminate the worker and close every owned pipe exactly once."""
         if self._idle_timer is not None:
             self._idle_timer.cancel()
@@ -610,7 +637,7 @@ class EmbeddingService:
             try:
                 proc.stdin.write('{"cmd":"quit"}\n')
                 proc.stdin.flush()
-                proc.wait(timeout=3)
+                proc.wait(timeout=max(0.0, timeout))
             except Exception:
                 try:
                     returncode = proc.poll()
@@ -621,7 +648,7 @@ class EmbeddingService:
                 if returncode is None or not isinstance(returncode, int):
                     try:
                         proc.kill()
-                        proc.wait(timeout=3)
+                        proc.wait(timeout=max(0.0, timeout))
                     except Exception:
                         pass
             finally: