release: v2.5.0 — audit every shipped surface, then repair what it found

Not a feature release. Twelve agents exercised the six user-facing surfaces
by RUNNING them rather than reading them; four more then attacked the fixes.
~134 defects closed across 41 files. Every number below was measured.

Three surfaces did not work at all:

- MCP could not survive a non-ASCII character under this host's default
  codec (writes stored mojibake or failed; a strict codec killed the process
  with no response). A 4301-digit int or ~3000 levels of nesting — both
  reachable through an advertised tool argument, before validation — escaped
  the too-narrow `except json.JSONDecodeError` and killed the server.
  `params: null`, which many clients send for "no params", consumed the id
  and never answered.
- The web viewer answered ZERO requests: one idle TCP pre-connect wedged a
  single-threaded HTTPServer with no handler timeout, and `webbrowser.open`
  triggers exactly that. It also sent `Access-Control-Allow-Origin: *`, and
  anything POSTed is injected into the next session — a prompt-injection
  channel — while POST itself rewrote the WRONG project's MEMORY.md.
- The standalone installer shipped NO user-facing surfaces: `~/.claude` held
  `hooks/` and `settings.json` and nothing else. With no plan-refiner agent,
  PLAN.md could never be populated — the v2.2 headline feature was dead on
  that layout. It also crashed AFTER copying files on any settings.json it
  could not parse (6 of 9 realistic shapes), leaving a half-installed tree.

Data integrity:

- Cross-project contamination. `_find_transcript_dir` matched on a SUBSTRING
  of the project basename; on this machine `core` matched 131 of 179 slug
  directories. A fixture seeded with 5 memories finished with 32 after a
  278,700-record foreign transcript was ingested. Path mangling also missed
  `_` and `.` (0 of 179 real dirs contain either), so any such path fell into
  that branch by construction. Fuzzy matching deleted; ownership now proved
  from the transcript's own `cwd`.
- The privacy filter failed OPEN above 100 tags — `<private>` content reached
  the API call and the DB. 16,000 unterminated tags took re.sub 9,517 ms and
  leaked the tail. Now a linear `str.find` scan, uncapped, failing CLOSED.
- `is_private` was computed after `_truncate_output` replaced a Read body
  with "(file content)", so a private file's path reached the API anyway.
- `/cc-mem sql` exited 0 while permanently committing `DROP TABLE`.

Hooks:

- The v2.2 live-plan anchor had never fired through its own hook: PostToolUse
  exited on the observation gate before reaching the plan block, and drift
  counters varied silently by mode. Plan control is not observation.
- Hooks with hard host timeouts did not bound their LLM wall-clock, though
  `call_llm`'s docstring requires it. session_start overran its 15s budget
  with the SHIPPED DEFAULT config (2 candidates x 20s); stop.py was measured
  being killed at 24.96s against 22s. `call_llm` gains an absolute `deadline`
  that clamps each leg to the time remaining — stronger than the arithmetic,
  because urlopen(timeout=) covers neither DNS nor the TLS handshake (a
  SUCCESSFUL leg measured 1.48x its nominal timeout).

Added:

- tests/test_surfaces.py — first automated coverage for MCP, the web viewer
  and the installer's settings.json matrix. All three had none, which is why
  these defects shipped. Now a third release gate.
- cc_memory/core/version.py — single source, importable under BOTH the nested
  and flat layouts (`import cc_memory` raises under flat, so the obvious
  approach could not work). Twelve literals across five files removed.
- excluded_projects now works; config.json stripped to keys code reads.

Gates: compileall - tomllib 2.5.0 - smoke 79 [OK] rc=0 - carryover 14 passed
- surfaces PASSED - i18n 3 in-sync - 6 version sites agree. Both exes rebuilt;
installer PE subsystem verified 2 (GUI) -> 3 (CONSOLE), so --cli is visible
and returns an exit code.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: skymanbp

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "cc-memory",
       "source": "./",
       "description": "Persistent memory: reconcile-on-write + LLM-judged semantic de-dup (no more stacked OR reworded duplicates), forced PROGRESS.md handoff with per-session annotation, live PLAN.md anchor, injection observability, FTS5 search, AI-judged extraction with Haiku + Ollama fallback.",
-      "version": "2.4.3",
+      "version": "2.5.0",
       "author": {"name": "skymanbp"},
       "repository": "https://github.com/skymanbp/cc-memory",
       "license": "MIT",

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-memory",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "Persistent memory for Claude Code — automatic save/restore across compactions and sessions. Anti-patch reconcile-on-write + LLM-judged semantic de-duplication, forced PROGRESS.md handoff with per-session annotation, live PLAN.md anchor, injection observability, FTS5 search, AI-judged extraction with Haiku + local Ollama fallback.",
   "author": {
     "name": "skymanbp",
@@ -9,5 +9,11 @@
   "homepage": "https://github.com/skymanbp/cc-memory",
   "repository": "https://github.com/skymanbp/cc-memory",
   "license": "MIT",
-  "keywords": ["memory", "persistence", "context", "handoff", "compact", "sqlite", "fts5", "anti-patch"]
+  "keywords": ["memory", "persistence", "context", "handoff", "compact", "sqlite", "fts5", "anti-patch"],
+  "mcpServers": {
+    "cc-memory": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/cc_memory/mcp/server.py"]
+    }
+  }
 }

CHANGELOG.md

@@ -3,14 +3,30 @@
 Build standalone exe files for cc-memory plugin.
 
 Produces:
-  dist/cc-memory-installer.exe   (one-click install on any machine)
-  dist/cc-memory-dashboard.exe   (visual memory management)
+  dist/cc-memory-installer.exe   (one-click install on any machine, CONSOLE app)
+  dist/cc-memory-dashboard.exe   (visual memory management, windowed)
 
 Requirements: pip install pyinstaller
 
-Packaging: bundles the subpackage layout (cc_memory/{core,hooks,llm,cli,mcp,ui}/)
-into cc_memory_files/ so the installer can mirror it under ~/.claude/hooks/cc-memory/.
+Packaging: bundles three payloads.
+  cc_memory_files/<subdir>/   the python package (mirrors ui/installer.py
+                              SUBPACKAGE_FILES), laid out FLAT under
+                              ~/.claude/hooks/cc-memory/ by the installer.
+  cc_memory_surfaces/<rel>    commands/ agents/ skills/ — the user-facing Claude
+                              Code surfaces, installed into ~/.claude/. They are
+                              NOT part of the package, so without this bundle a
+                              standalone install ships no /cc-mem, no /ccm-load
+                              and no plan-refiner subagent (PLAN.md then can
+                              never be populated).
+  cc_memory_meta/hooks.json   the hook-timeout source of truth, read by
+                              installer._declared_hook_timeouts().
+
+The installer is built WITHOUT --windowed: its --cli branch is the documented
+headless path, and a GUI-subsystem binary prints nothing, returns no exit code
+to the shell, and turns any unhandled exception into a modal dialog that hangs
+forever with no console to show it. Tk still opens fine from a console app.
 """
+import re
 import shutil
 import subprocess
 import sys
@@ -27,7 +43,8 @@
     "":      ["__init__.py", "config.json"],
     "core":  ["__init__.py", "auth.py", "consolidate.py", "db.py",
               "encoding_setup.py", "extractor.py", "idle.py", "logger.py",
-              "modes.py", "plan.py", "privacy.py", "progress.py"],
+              "modes.py", "plan.py", "privacy.py", "progress.py",
+              "version.py"],
     "hooks": ["__init__.py", "consolidate_async.py", "post_tool_use.py",
               "pre_compact.py", "session_start.py", "stop.py", "user_prompt.py"],
     "llm":   ["__init__.py", "ccl_backend.py", "memory_writer.py"],
@@ -36,6 +53,31 @@
     "ui":    ["__init__.py", "dashboard.py", "installer.py", "web_viewer.py"],
 }
 
+# User-facing surfaces. Mirrors ui/installer.py SURFACE_FILES.
+SURFACE_FILES = [
+    "commands/cc-mem.md",
+    "agents/plan-refiner.md",
+    "agents/plan-guardian.md",
+    "skills/ccm-load/SKILL.md",
+    "skills/save-memories/SKILL.md",
+]
+
+# Non-package data the installer reads at runtime.
+META_FILES = ["hooks/hooks.json"]
+
+
+def _version():
+    """Read the canonical version. Never a literal in this file."""
+    for probe in (SRC / "core" / "version.py", SRC / "__init__.py"):
+        try:
+            txt = probe.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        m = re.search(r'^__version__\s*=\s*["\']([^"\']+)["\']', txt, re.M)
+        if m:
+            return m.group(1)
+    return "unknown"
+
 
 def _flat_file_list():
     """Yield (src_path, dest_subdir_in_bundle) for every plugin file."""
@@ -49,89 +91,97 @@ def _flat_file_list():
     return pairs
 
 
-def _check_files():
-    missing = [str(p) for p, _ in _flat_file_list() if not p.exists()]
+def _surface_file_list():
+    """Yield (src_path, dest_subdir_in_bundle) for every shipped surface."""
+    pairs = []
+    for rel in SURFACE_FILES:
+        sub = Path(rel).parent.as_posix()
+        pairs.append((ROOT / rel, f"cc_memory_surfaces/{sub}"))
+    return pairs
+
+
+def _meta_file_list():
+    return [(ROOT / rel, "cc_memory_meta") for rel in META_FILES]
+
+
+def _check_files(pairs):
+    missing = [str(p) for p, _ in pairs if not p.exists()]
     if missing:
         print("ERROR: Missing files:")
         for m in missing:
             print(f"  {m}")
         sys.exit(1)
 
 
+def _data_args(pairs):
+    # PyInstaller --add-data syntax: "src;dest" on Windows, "src:dest" on Unix
+    sep = ";" if sys.platform == "win32" else ":"
+    args = []
+    for src_path, dest in pairs:
+        args.extend(["--add-data", f"{src_path}{sep}{dest}"])
+    return args
+
+
+def _run(cmd, exe_name):
+    print(f"Running PyInstaller with {cmd.count('--add-data')} bundled files...")
+    result = subprocess.run(cmd, cwd=str(ROOT))
+    if result.returncode != 0:
+        print("\n[FAIL] Build failed")
+        sys.exit(1)
+    exe_path = DIST / exe_name
+    if exe_path.exists():
+        size_mb = exe_path.stat().st_size / 1024 / 1024
+        print(f"\n[OK] Built: {exe_path} ({size_mb:.1f} MB)")
+
+
 def build_installer():
     print("=" * 50)
-    print("  Building cc-memory-installer.exe (v2.4.3)")
+    print(f"  Building cc-memory-installer.exe (v{_version()})")
     print("=" * 50)
 
-    _check_files()
-
-    data_args = []
-    for src_path, dest in _flat_file_list():
-        # PyInstaller --add-data syntax: "src;dest" on Windows, "src:dest" on Unix
-        sep = ";" if sys.platform == "win32" else ":"
-        data_args.extend(["--add-data", f"{src_path}{sep}{dest}"])
+    pairs = _flat_file_list() + _surface_file_list() + _meta_file_list()
+    _check_files(pairs)
 
     cmd = [
         sys.executable, "-m", "PyInstaller",
         "--onefile",
-        "--windowed",
+        # Console, NOT --windowed: the installer's --cli branch prints 20+ lines
+        # and is the documented headless path. Tk is created on demand in main().
+        "--console",
         "--name", "cc-memory-installer",
         "--icon", "NONE",
         "--hidden-import", "sqlite3",
         "--hidden-import", "_sqlite3",
         "--collect-all", "sqlite3",
-        *data_args,
+        *_data_args(pairs),
         str(SRC / "ui" / "installer.py"),
     ]
-
-    print(f"Running PyInstaller with {len(data_args)//2} bundled files...")
-    result = subprocess.run(cmd, cwd=str(ROOT))
-    if result.returncode == 0:
-        exe_path = DIST / "cc-memory-installer.exe"
-        if exe_path.exists():
-            size_mb = exe_path.stat().st_size / 1024 / 1024
-            print(f"\n[OK] Built: {exe_path} ({size_mb:.1f} MB)")
-    else:
-        print("\n[FAIL] Build failed")
-        sys.exit(1)
+    _run(cmd, "cc-memory-installer.exe")
 
 
 def build_dashboard():
     print("=" * 50)
-    print("  Building cc-memory-dashboard.exe (v2.4.3)")
+    print(f"  Building cc-memory-dashboard.exe (v{_version()})")
     print("=" * 50)
 
-    _check_files()
-
-    # Dashboard needs everything the installer does (it imports core + llm).
-    data_args = []
-    for src_path, dest in _flat_file_list():
-        sep = ";" if sys.platform == "win32" else ":"
-        data_args.extend(["--add-data", f"{src_path}{sep}{dest}"])
+    # Dashboard needs everything the installer's package bundle has (it imports
+    # core + llm), but none of the surfaces/meta — it never installs anything.
+    pairs = _flat_file_list()
+    _check_files(pairs)
 
     cmd = [
         sys.executable, "-m", "PyInstaller",
         "--onefile",
-        "--windowed",
+        "--windowed",          # pure GUI: correct here, wrong for the installer
         "--name", "cc-memory-dashboard",
         "--icon", "NONE",
         "--hidden-import", "sqlite3",
         "--hidden-import", "_sqlite3",
         "--collect-all", "sqlite3",
-        *data_args,
+        *_data_args(pairs),
         str(SRC / "ui" / "dashboard.py"),
     ]
-
-    print(f"Running PyInstaller with {len(data_args)//2} bundled files...")
-    result = subprocess.run(cmd, cwd=str(ROOT))
-    if result.returncode == 0:
-        exe_path = DIST / "cc-memory-dashboard.exe"
-        if exe_path.exists():
-            size_mb = exe_path.stat().st_size / 1024 / 1024
-            print(f"\n[OK] Built: {exe_path} ({size_mb:.1f} MB)")
-    else:
-        print("\n[FAIL] Build failed")
-        sys.exit(1)
+    _run(cmd, "cc-memory-dashboard.exe")
 
 
 if __name__ == "__main__":

CLAUDE.md

@@ -1,6 +1,30 @@
 """
 cc-memory — Claude Code persistent memory plugin.
 
+v2.5.0: A readiness audit of every shipped surface, and the repair of what it
+      found. Three surfaces did not work at all: the MCP server could not
+      survive a non-ASCII character under a locale codec, the web viewer
+      answered zero requests because one idle TCP pre-connect wedged it, and
+      the standalone installer shipped NO user-facing surfaces — no /cc-mem,
+      no skills, no subagents — so the v2.2 live-plan feature could never work
+      on that layout. Meanwhile `_find_transcript_dir` matched on a *substring*
+      of the project basename (131 of 179 real directories matched `core`), so
+      one project's transcripts were being LLM-extracted into another project's
+      database and re-injected forever after; a fixture seeded with 5 memories
+      finished with 32. The v2.2 plan anchor had also never fired through its
+      own hook, because PostToolUse exited on the observation gate before
+      reaching the plan block.
+      Also: the privacy filter failed OPEN above 100 tags (now a linear,
+      uncapped, fail-closed scan); hooks with hard host timeouts now bound
+      their LLM wall-clock with an absolute deadline, not just per-leg socket
+      timeouts (`urlopen(timeout=)` covers neither DNS nor the TLS handshake —
+      a *successful* leg was measured at 1.48x its nominal timeout); and the
+      version string is single-sourced from `core/version.py`, which is
+      importable under BOTH the nested and the flat install layouts.
+      New: `tests/test_surfaces.py`, the first automated coverage for the MCP
+      server, the web viewer and the installer's settings.json shape matrix —
+      all three previously had none, which is why these defects shipped.
+
 v2.4.2: Bounded transcript reads. An unbounded full-file load in the PreCompact
       hook killed compaction on long-lived projects — a 2.1 GiB transcript
       parses at ~25 MiB/s (~88s) against a 120s budget, so the hook was
@@ -61,4 +85,6 @@
       PROGRESS.md forced-handoff replaces SESSION_HANDOFF.md.
       MEMORY.md auto-regenerates on every write.
 """
-__version__ = "2.4.3"
+from .core.version import __version__  # single source: cc_memory/core/version.py
+
+__all__ = ["__version__"]