superlocalmemory 3.7.8 → 3.8.1

package/src/superlocalmemory/cli/commands.py

@@ -40,6 +40,14 @@ def _cmd_db_dispatch(args: Namespace) -> None:
     sys.exit(2)
 
 
+def _cmd_mesh_dispatch(args: Namespace) -> None:
+    """Route ``slm mesh ...`` inspection subcommands (M-03)."""
+    from superlocalmemory.cli.mesh_cmd import cmd_mesh
+    rc = cmd_mesh(args)
+    if rc:
+        sys.exit(rc)
+
+
 def _cmd_escape_disable(args: Namespace) -> None:
     from superlocalmemory.cli.escape_hatch import cmd_disable
     cmd_disable(args)
@@ -98,6 +106,11 @@ def _cmd_help_optimize(args: Namespace) -> None:
     cmd_help_optimize(args)
 
 
+def _cmd_loop(args: Namespace) -> None:
+    from superlocalmemory.cli.loop_cmd import cmd_loop
+    cmd_loop(args)
+
+
 # ---- end SLM v3.6 Optimize dispatch functions ----
 
 
@@ -146,7 +159,10 @@ def cmd_session(args: Namespace) -> None:
 def dispatch(args: Namespace) -> None:
     """Route CLI command to the appropriate handler."""
     # Auto-install/upgrade hooks on version change (single file read, ~0.1ms)
-    if args.command not in ("hooks", "codex", "init", "mcp"):
+    if (
+        args.command not in ("hooks", "codex", "init", "mcp")
+        and not getattr(args, "dry_run", False)
+    ):
         try:
             from superlocalmemory.hooks.claude_code_hooks import auto_install_if_needed
             auto_install_if_needed()
@@ -201,6 +217,8 @@ def dispatch(args: Namespace) -> None:
         "context": _cmd_context_dispatch,
         # V3.4.22 LLD-06 additive schema migrations
         "db": _cmd_db_dispatch,
+        # V3.7.9 M-03 — terminal mesh inspection
+        "mesh": _cmd_mesh_dispatch,
         # V3.4.22 Stage 8 SB-5 — MASTER-PLAN §8 escape hatches.
         "disable": _cmd_escape_disable,
         "enable": _cmd_escape_enable,
@@ -218,6 +236,8 @@ def dispatch(args: Namespace) -> None:
         "compress": _cmd_compress,
         "proxy": _cmd_proxy,
         "help-optimize": _cmd_help_optimize,
+        # V3.8.0 bounded loops (gate-verified agent loops, SLM-backed ledger)
+        "loop": _cmd_loop,
     }
     handler = handlers.get(args.command)
     if handler:
@@ -345,6 +365,11 @@ def cmd_serve(args: Namespace) -> None:
     else:
         from superlocalmemory.infra.data_root import state_path
         print(f"Failed to start daemon. Check {state_path('logs', 'daemon.log')}")
+        # INT-H-02: exit non-zero so callers can detect the failure. The plugin
+        # launcher (plugin/scripts/slm-launch) guards on this exit code and
+        # refuses to open a direct MCP writer against a broken daemon; without
+        # the non-zero exit that guard was a dead no-op.
+        sys.exit(1)
 
 
 # -- Ingestion Adapters (V3.4.3) ------------------------------------------
@@ -610,6 +635,8 @@ def cmd_config(args: Namespace) -> None:
     elif action == "set":
         _ALLOWED_CONFIG_KEYS = {
             "evolution.enabled", "evolution.backend", "evolution.max_evolutions_per_cycle",
+            "evolution.mutation_model", "evolution.verify_model",
+            "evolution.confirm_model",
             "mesh_enabled", "daemon_idle_timeout", "entity_compilation_enabled",
             "graph_backend", "vector_backend", "scale_engine_state",
             "scope.default_scope", "scope.recall_include_global",
@@ -677,6 +704,31 @@ def cmd_config(args: Namespace) -> None:
                 print(f"Error: {message}")
             sys.exit(1)
 
+        _MODEL_KEYS = {
+            "evolution.mutation_model", "evolution.verify_model",
+            "evolution.confirm_model",
+        }
+        if key in _MODEL_KEYS:
+            from superlocalmemory.evolution.model_selection import _MODEL_ALIASES
+
+            accepted = set(_MODEL_ALIASES) | {"", "auto"}
+            sval = str(parsed_value)
+            if sval not in accepted:
+                allowed = ", ".join(["auto", *sorted(_MODEL_ALIASES)])
+                message = f"{key} must be one of: {allowed}"
+                if use_json:
+                    from superlocalmemory.cli.json_output import json_print
+                    json_print("config", error={
+                        "code": "INVALID_VALUE", "message": message,
+                    })
+                else:
+                    print(f"Error: {message}")
+                sys.exit(1)
+            # Normalise the "auto" sentinel to the empty string the
+            # resolver treats as "pick the cheapest for the backend".
+            if sval == "auto":
+                parsed_value = ""
+
         if key.startswith("scope."):
             from superlocalmemory.cli.daemon import daemon_request, is_daemon_running
 
@@ -727,6 +779,18 @@ def cmd_config(args: Namespace) -> None:
             })
         else:
             print(f"{key}: {old_value} -> {parsed_value}")
+            if key == "evolution.enabled" and parsed_value is True:
+                print(
+                    "\n⚠  Skill evolution is now ON. It makes background "
+                    "LLM calls during consolidation\n"
+                    "   (capped at 10 calls/cycle, 3 cycles/day). It defaults "
+                    "to the lowest-cost model\n"
+                    "   for your backend (Claude → Haiku, Ollama → "
+                    "local/free).\n"
+                    "   Pick models: slm config set evolution.mutation_model "
+                    "<auto|haiku|sonnet|ollama>\n"
+                    "   Turn off:    slm config set evolution.enabled false"
+                )
 
     else:
         if use_json:
@@ -897,16 +961,22 @@ def _agents_md_source_factory():
     Gracefully skips if absent — never fails the MCP write.
     """
     from pathlib import Path
+    import sysconfig
 
     # Resolve relative to the package root (src/superlocalmemory/../../)
     _pkg_root = Path(__file__).resolve().parents[3]
-    _agents_src = _pkg_root / "plugin-src" / "rules" / "AGENTS.md"
+    _candidates = (
+        _pkg_root / "plugin-src" / "rules" / "AGENTS.md",
+        Path(sysconfig.get_path("data")) / "share" / "superlocalmemory"
+        / "portable-kit" / "rules" / "AGENTS.md",
+    )
 
     def _read() -> str | None:
-        if _agents_src.exists():
-            return _agents_src.read_text(encoding="utf-8")
+        for candidate in _candidates:
+            if candidate.exists():
+                return candidate.read_text(encoding="utf-8")
         logger.warning(
-            "WP-05 AGENTS.md not found at %s — skipping AGENTS.md write", _agents_src
+            "WP-05 AGENTS.md is not bundled — skipping AGENTS.md write"
         )
         return None
 
@@ -947,9 +1017,10 @@ def cmd_connect(args: Namespace) -> None:
                 here=here,
                 profile=profile,
                 agents_md_source=_agents_md_source_factory(),
+                dry_run=getattr(args, "dry_run", False),
             )
 
-            if not result.get("error"):
+            if not result.get("error") and not getattr(args, "dry_run", False):
                 from superlocalmemory.infra.local_diagnostics import record_operation
 
                 record_operation("activation", client=ide_arg)
@@ -968,6 +1039,7 @@ def cmd_connect(args: Namespace) -> None:
                 sys.exit(1)
 
             status_sym = {"wrote": "[+]", "merged": "[~]", "unchanged": "[=]",
+                          "would_write": "[~]",
                           "skipped": "[s]", "error": "[!]"}.get(
                 result["mcp_config"], "[?]"
             )
@@ -996,6 +1068,7 @@ def cmd_connect(args: Namespace) -> None:
     from superlocalmemory.hooks.ide_connector import IDEConnector
 
     connector = IDEConnector()
+    dry_run = bool(getattr(args, "dry_run", False))
 
     if getattr(args, 'json', False):
         from superlocalmemory.cli.json_output import json_print
@@ -1007,6 +1080,14 @@ def cmd_connect(args: Namespace) -> None:
         elif getattr(args, "ide", None):
             success = connector.connect(args.ide)
             json_print("connect", data={"ide": args.ide, "connected": success})
+        elif dry_run:
+            json_print(
+                "connect",
+                data={
+                    "dry_run": True,
+                    "would_configure": connector.get_status(),
+                },
+            )
         else:
             json_print("connect", data={"results": connector.connect_all()},
                        next_actions=[
@@ -1020,6 +1101,12 @@ def cmd_connect(args: Namespace) -> None:
             mark = "[+]" if s["installed"] else "[-]"
             print(f"  {mark} {s['name']:20s} {s['config_path']}")
         return
+    if dry_run:
+        status = connector.get_status()
+        print("Dry run — no IDE, hook, config, or SLM data files were written.")
+        for item in status:
+            print(f"  would inspect/configure: {item['name']} ({item['config_path']})")
+        return
     if getattr(args, "ide", None):
         success = connector.connect(args.ide)
         print(f"{'Connected' if success else 'Failed'}: {args.ide}")
@@ -1271,10 +1358,12 @@ def cmd_recall(args: Namespace) -> None:
                 scope_qs += f"&include_global={str(include_global).lower()}"
             if include_shared is not None:
                 scope_qs += f"&include_shared={str(include_shared).lower()}"
+            _window = getattr(args, "window", "") or ""
+            window_qs = f"&window={quote(_window)}" if _window else ""
             result = daemon_request(
                 "GET",
                 f"/recall?q={quote(args.query)}&limit={args.limit}"
-                f"&session_id={quote(session_id)}{fast_qs}{scope_qs}",
+                f"&session_id={quote(session_id)}{fast_qs}{scope_qs}{window_qs}",
             )
             if result and "results" in result:
                 # Format daemon response same as engine response
@@ -1294,8 +1383,10 @@ def cmd_recall(args: Namespace) -> None:
                 for i, r in enumerate(result["results"], 1):
                     print(f"  {i}. [{r['score']:.2f}] {r['content']}")
                 return
-    except Exception:
-        pass  # Fall through to direct engine
+    except Exception as _exc:  # noqa: BLE001
+        logger.warning(
+            "Daemon recall failed, falling back to direct engine: %s", _exc
+        )
 
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
@@ -1310,6 +1401,7 @@ def cmd_recall(args: Namespace) -> None:
             fast=getattr(args, "fast", False),
             include_global=include_global,
             include_shared=include_shared,
+            window=getattr(args, "window", "") or None,
         )
     except Exception as exc:
         if use_json:
@@ -1394,12 +1486,32 @@ def cmd_forget(args: Namespace) -> None:
     from superlocalmemory.core.config import SLMConfig
 
     use_json = getattr(args, 'json', False)
+    dry_run = getattr(args, 'dry_run', False)
+    raw_query = getattr(args, 'query', None)
+
+    # F3: `query` is optional so `slm forget --dry-run` can preview every memory.
+    # Deletion ALWAYS requires an explicit query — a bare `slm forget` must never
+    # mass-delete. In dry-run mode a missing query means "match all" (preview).
+    if raw_query is None and not dry_run:
+        msg = (
+            "A query is required to delete. Preview everything with "
+            "'slm forget --dry-run', or delete matches with 'slm forget <query>'."
+        )
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("forget", error={"code": "QUERY_REQUIRED", "message": msg})
+        else:
+            print(msg)
+        sys.exit(2)
+
+    query_lower = "" if raw_query is None else raw_query.lower()
+    query_label = raw_query if raw_query is not None else "*all*"
+
     try:
         config = SLMConfig.load()
         engine = MemoryEngine(config)
         engine.initialize()
         facts = engine._db.get_all_facts(engine.profile_id)
-        query_lower = args.query.lower()
         matches = [f for f in facts if query_lower in f.content.lower()]
     except Exception as exc:
         if use_json:
@@ -1408,8 +1520,6 @@ def cmd_forget(args: Namespace) -> None:
             sys.exit(1)
         raise
 
-    dry_run = getattr(args, 'dry_run', False)
-
     def delete_fact_authorized_for_cli(fact_id: str) -> None:
         from superlocalmemory.core.engine_ingestion import local_trusted_actor_id
         from superlocalmemory.core.mutations import delete_fact_authorized
@@ -1450,12 +1560,12 @@ def cmd_forget(args: Namespace) -> None:
                 "matches": match_items,
                 "hint": "Add --yes to confirm deletion",
             }, next_actions=[
-                {"command": f"slm forget '{args.query}' --json --yes", "description": "Confirm deletion"},
+                {"command": f"slm forget '{query_label}' --json --yes", "description": "Confirm deletion"},
             ])
         return
 
     if not matches:
-        print(f"No memories matching '{args.query}'")
+        print(f"No memories matching '{query_label}'")
         return
     print(f"Found {len(matches)} matching memories:")
     for f in matches[:10]:
@@ -1479,16 +1589,86 @@ def cmd_forget(args: Namespace) -> None:
 
 def cmd_delete(args: Namespace) -> None:
     """Delete a specific memory by exact fact ID."""
+    import urllib.parse
+
+    from superlocalmemory.cli.daemon import daemon_request, is_daemon_running
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
 
     use_json = getattr(args, 'json', False)
+    fact_id = args.fact_id.strip()
+    if is_daemon_running():
+        path = "/api/memories/" + urllib.parse.quote(fact_id, safe="")
+        confirmed = getattr(args, "yes", False)
+        content = ""
+        if not confirmed:
+            detail = daemon_request(
+                "GET",
+                "/api/facts/" + urllib.parse.quote(fact_id, safe=""),
+            )
+            if not isinstance(detail, dict):
+                if use_json:
+                    from superlocalmemory.cli.json_output import json_print
+                    json_print("delete", error={
+                        "code": "DAEMON_MUTATION_FAILED",
+                        "message": "Resident daemon could not resolve the memory.",
+                    })
+                    sys.exit(1)
+                raise RuntimeError("Resident daemon could not resolve the memory.")
+            content = str(detail.get("content") or "")
+            if use_json:
+                from superlocalmemory.cli.json_output import json_print
+                json_print("delete", data={
+                    "fact_id": fact_id,
+                    "content": content[:120],
+                    "deleted": False,
+                    "hint": "Add --yes to confirm deletion",
+                }, next_actions=[
+                    {
+                        "command": f"slm delete {fact_id} --json --yes",
+                        "description": "Confirm deletion",
+                    },
+                ])
+                return
+            print(f"Memory: {content[:120]}")
+            confirmed = input("Delete this memory? [y/N] ").strip().lower() in (
+                "y", "yes",
+            )
+            if not confirmed:
+                print("Cancelled.")
+                return
+
+        result = daemon_request("DELETE", path)
+        if not isinstance(result, dict) or not result.get("success"):
+            if use_json:
+                from superlocalmemory.cli.json_output import json_print
+                json_print("delete", error={
+                    "code": "DAEMON_MUTATION_FAILED",
+                    "message": "Resident daemon rejected the delete operation.",
+                })
+                sys.exit(1)
+            raise RuntimeError("Resident daemon rejected the delete operation.")
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print(
+                "delete",
+                data={"deleted": fact_id, "content": content[:120]},
+                next_actions=[
+                    {
+                        "command": "slm list --json",
+                        "description": "Verify remaining memories",
+                    },
+                ],
+            )
+        else:
+            print(f"Deleted: {fact_id}")
+        return
+
     try:
         config = SLMConfig.load()
         engine = MemoryEngine(config)
         engine.initialize()
 
-        fact_id = args.fact_id.strip()
         rows = engine._db.execute(
             "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
             (fact_id, engine.profile_id),
@@ -1558,6 +1738,9 @@ def cmd_delete(args: Namespace) -> None:
 
 def cmd_update(args: Namespace) -> None:
     """Update the content of a specific memory by exact fact ID."""
+    import urllib.parse
+
+    from superlocalmemory.cli.daemon import daemon_request, is_daemon_running
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
 
@@ -1573,6 +1756,34 @@ def cmd_update(args: Namespace) -> None:
         print("Error: content cannot be empty")
         return
 
+    if is_daemon_running():
+        path = "/api/memories/" + urllib.parse.quote(fact_id, safe="")
+        result = daemon_request("PATCH", path, {"content": new_content})
+        if not isinstance(result, dict) or not result.get("success"):
+            if use_json:
+                from superlocalmemory.cli.json_output import json_print
+                json_print("update", error={
+                    "code": "DAEMON_MUTATION_FAILED",
+                    "message": "Resident daemon rejected the update operation.",
+                })
+                sys.exit(1)
+            raise RuntimeError("Resident daemon rejected the update operation.")
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("update", data={
+                "fact_id": fact_id,
+                "new_content": new_content[:120],
+            }, next_actions=[
+                {
+                    "command": "slm list --json",
+                    "description": "List recent memories",
+                },
+            ])
+        else:
+            print(f"New: {new_content[:100]}")
+            print(f"Updated: {fact_id}")
+        return
+
     try:
         config = SLMConfig.load()
         engine = MemoryEngine(config)
@@ -1835,8 +2046,8 @@ def cmd_health(args: Namespace) -> None:
 
     print("Math Layer Health:")
     print(f"  Total facts: {len(facts)}")
-    print(f"  Fisher-Rao indexed: {fisher_count}/{len(facts)}")
-    print(f"  Langevin positioned: {langevin_count}/{len(facts)}")
+    print(f"  Math layer indexed: {fisher_count}/{len(facts)}")
+    print(f"  Lifecycle positioned: {langevin_count}/{len(facts)}")
     print(f"  Mode: {config.mode.value.upper()}")
 
 

package/src/superlocalmemory/cli/compress_cmd.py

@@ -118,8 +118,13 @@ def cmd_compress_prose(args: Namespace) -> None:
     cfg = store.get()
 
     fields: dict = {"compress_prose": (value == "on")}
-    if value == "on" and not cfg.compress_enabled:
-        fields["compress_enabled"] = True
+    if value == "on":
+        # Prose (Layer 2) only fires in aggressive mode, so turning it on sets a
+        # COHERENT state — it can never be left enabled-but-inert in safe mode.
+        if not cfg.compress_enabled:
+            fields["compress_enabled"] = True
+        if cfg.compress_mode != "aggressive":
+            fields["compress_mode"] = "aggressive"
 
     try:
         cfg = dataclasses.replace(cfg, **fields)
@@ -129,13 +134,18 @@ def cmd_compress_prose(args: Namespace) -> None:
         sys.exit(1)
 
     if use_json:
-        print(json.dumps({"status": "ok", "compress_prose": value == "on"}))
+        print(json.dumps({
+            "status": "ok",
+            "compress_prose": value == "on",
+            "compress_mode": cfg.compress_mode,
+        }))
         return
 
     print(f"Prose compression (LLMLingua-2): {'ENABLED' if value == 'on' else 'DISABLED'}.")
     if value == "on":
-        print("  Requires: compress_mode=aggressive and llmlingua package installed.")
-        print("  Run: slm compress mode aggressive  (if not already set)")
-    if value == "on" and "compress_enabled" in fields:
-        print("  (also enabled global compress)")
+        if "compress_mode" in fields:
+            print("  Compression mode set to 'aggressive' (required for Layer 2).")
+        print("  Requires the llmlingua package for lossy prose compression.")
+        if "compress_enabled" in fields:
+            print("  (also enabled global compression)")
     print("Daemon hot-reload: active within 2s.")

package/src/superlocalmemory/cli/daemon.py

@@ -267,6 +267,13 @@ def daemon_request(
         if capability is not None:
             headers["X-SLM-Daemon-Capability"] = capability
             headers["X-SLM-Target-Instance"] = descriptor.instance_id
+        # Daemon ownership proves that this CLI targets the local instance; it
+        # does not replace a dashboard user's profile-scoped authorization in
+        # governed workspaces. The user opts in by supplying an explicit
+        # session through the process environment (never logged or persisted).
+        user_session = os.environ.get("SLM_USER_SESSION", "").strip()
+        if user_session:
+            headers["X-SLM-User-Session"] = user_session
         req = urllib.request.Request(url, data=data, headers=headers, method=method)
         resp = urllib.request.urlopen(req, timeout=timeout_seconds)
         return json.loads(resp.read().decode())

package/src/superlocalmemory/cli/loop_cmd.py

@@ -0,0 +1,187 @@
+"""``slm loop`` — inspect and demonstrate bounded loops backed by SLM memory.
+
+Subcommands:
+
+* ``slm loop demo``            run a built-in, keyless convergence demo (stub
+                              proposer + deterministic gate) and persist every
+                              lap to SLM memory. Proves the engine + ledger
+                              end to end without a credentialed agent.
+* ``slm loop history [--name]`` list recorded loop runs from SLM memory.
+* ``slm loop show <run_id>``   show every lap of one run.
+
+The durable value here is that a loop's history lives in the same SLM data
+root as everything else the agent remembers — queryable via ``slm recall`` and
+visible in the dashboard. Reads and the demo run through an in-process engine
+store rooted at the active data root (``SLM_DATA_DIR`` or
+``~/.superlocalmemory``); point ``SLM_DATA_DIR`` elsewhere to sandbox a run.
+"""
+
+from __future__ import annotations
+
+import json
+from argparse import Namespace
+from pathlib import Path
+from typing import Any
+
+from superlocalmemory.infra.data_root import canonical_data_root
+from superlocalmemory.loops import (
+    Bounds,
+    LapResult,
+    SLMMemoryLedger,
+    Verdict,
+    open_engine_store,
+    run_bounded_loop,
+)
+
+
+def _data_root() -> Path:
+    return canonical_data_root()
+
+
+class _FailOpenLedger:
+    """Wrap a ledger so a memory write hiccup never aborts a running loop.
+
+    A ledger is observability; the loop's correctness comes from the gate.
+    Write errors are counted and surfaced after the run rather than raised
+    mid-flight, so we never silently pretend they did not happen.
+    """
+
+    def __init__(self, inner: Any) -> None:
+        self._inner = inner
+        self.write_errors: list[str] = []
+
+    def record(self, entry: Any) -> None:
+        try:
+            self._inner.record(entry)
+        except Exception as exc:  # pragma: no cover - defensive path
+            self.write_errors.append(f"lap {getattr(entry, 'lap', '?')}: {exc}")
+
+    def laps(self, run_id: str) -> list:
+        return self._inner.laps(run_id)
+
+    def runs(self, name: str) -> list:
+        return self._inner.runs(name)
+
+
+def _open_ledger() -> tuple[SLMMemoryLedger, Any]:
+    store = open_engine_store(_data_root() / "memory.db")
+    return SLMMemoryLedger(store), store
+
+
+def cmd_loop(args: Namespace) -> None:
+    action = getattr(args, "loop_command", None)
+    if action == "demo":
+        _cmd_demo(args)
+    elif action == "history":
+        _cmd_history(args)
+    elif action == "show":
+        _cmd_show(args)
+    else:
+        print("Usage: slm loop {demo|history|show} [options]")
+
+
+def _cmd_demo(args: Namespace) -> None:
+    """Run the convergence demo: the gate fails twice, then passes on lap 3."""
+    iterations = int(getattr(args, "iterations", 10) or 10)
+    as_json = bool(getattr(args, "json", False))
+    pass_on = 3
+
+    ledger, store = _open_ledger()
+    guarded = _FailOpenLedger(ledger)
+    try:
+        outcome = run_bounded_loop(
+            "convergence-demo",
+            bounds=Bounds(max_iterations=iterations),
+            runner=lambda lap: LapResult(changed=True, tokens=8),
+            gate=lambda lap: Verdict(lap >= pass_on, f"demo gate: lap {lap}"),
+            ledger=guarded,
+        )
+        laps = guarded.laps(outcome.run_id)
+    finally:
+        store.close()
+
+    if as_json:
+        print(json.dumps({
+            "status": outcome.status.value,
+            "reason": outcome.reason,
+            "laps": outcome.laps,
+            "run_id": outcome.run_id,
+            "ledger": [
+                {"lap": e.lap, "decision": e.decision, "passed": e.passed}
+                for e in laps
+            ],
+            "write_errors": guarded.write_errors,
+        }, indent=2))
+        return
+
+    mark = "✓" if outcome.ok else "✗"
+    print(f"{mark} [{outcome.status.value}] {outcome.reason} (laps: {outcome.laps})")
+    for e in laps:
+        gate = "gate-pass" if e.passed else "gate-fail"
+        print(f"   lap {e.lap}: {e.decision:<8} {gate}  {e.detail}")
+    print(f"run_id: {outcome.run_id}  (recall with tag loop:convergence-demo)")
+    if guarded.write_errors:
+        print(f"WARNING: {len(guarded.write_errors)} ledger write error(s): "
+              f"{guarded.write_errors[0]}")
+
+
+def _cmd_history(args: Namespace) -> None:
+    name = getattr(args, "name", None) or "convergence-demo"
+    as_json = bool(getattr(args, "json", False))
+    ledger, store = _open_ledger()
+    try:
+        run_ids = ledger.runs(name)
+        rows = []
+        for rid in run_ids:
+            laps = ledger.laps(rid)
+            last = laps[-1] if laps else None
+            rows.append({
+                "run_id": rid,
+                "laps": len(laps),
+                "final": last.decision if last else "unknown",
+                "ts": last.ts if last else "",
+            })
+    finally:
+        store.close()
+
+    if as_json:
+        print(json.dumps({"name": name, "runs": rows}, indent=2))
+        return
+    if not rows:
+        print(f"No recorded runs for loop '{name}'.")
+        return
+    print(f"Runs for loop '{name}':")
+    for r in rows:
+        print(f"  {r['run_id']:<28} laps={r['laps']:<3} final={r['final']:<8} {r['ts']}")
+
+
+def _cmd_show(args: Namespace) -> None:
+    run_id = getattr(args, "run_id", None)
+    as_json = bool(getattr(args, "json", False))
+    if not run_id:
+        print("Usage: slm loop show <run_id>")
+        return
+    ledger, store = _open_ledger()
+    try:
+        laps = ledger.laps(run_id)
+    finally:
+        store.close()
+
+    if as_json:
+        print(json.dumps({
+            "run_id": run_id,
+            "laps": [
+                {"lap": e.lap, "ts": e.ts, "decision": e.decision,
+                 "passed": e.passed, "detail": e.detail, "budget": e.budget}
+                for e in laps
+            ],
+        }, indent=2))
+        return
+    if not laps:
+        print(f"No ledger entries for run '{run_id}'.")
+        return
+    print(f"Loop run {run_id} ({laps[0].name}):")
+    for e in laps:
+        gate = "gate-pass" if e.passed else "gate-fail"
+        print(f"  lap {e.lap}: {e.decision:<8} {gate}  {e.detail}  "
+              f"[tokens={e.budget.get('tokens', 0)}]")