mindslice 0.1.0__py3-none-any.whl

mindslice/interfaces/cli.py

@@ -0,0 +1,392 @@
+"""``mindslice`` command-line interface (memory primitives plus ``status``, ``boot``, ``init`` and ``mcp``)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+from .. import __version__
+from ..model.addressing import normalize_alias
+from ..operations.boot import render_markdown as render_boot
+from .cli_addressing import reference as cli_reference
+from ..errors import ApplyConflictError, MindSliceError
+from ..operations.status import render_status
+from ..workspace import Workspace
+from . import render
+
+
+def _follow(value: str | None) -> bool | list[str]:
+    if value is None:
+        return True
+    low = value.strip().lower()
+    if low in ("", "all", "true", "yes", "1"):
+        return True
+    if low in ("none", "false", "no", "0"):
+        return False
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def _emit(data: Any, compact: bool) -> None:
+    text = json.dumps(data, ensure_ascii=False, indent=None if compact else 2)
+    sys.stdout.write(text + "\n")
+
+
+def _output(args: argparse.Namespace, data: Any, renderer: render.Renderer) -> None:
+    """Human-readable by default; the result dict as JSON with ``--json`` (or ``--compact``)."""
+    if args.json:
+        _emit(data, args.compact)
+        return
+    text = renderer(data)
+    if text:
+        sys.stdout.write(text if text.endswith("\n") else text + "\n")
+
+
+def _error(args: argparse.Namespace, error: dict[str, Any]) -> None:
+    """Errors go to stderr in both modes, with the same stable ``code``."""
+    if args.json:
+        sys.stderr.write(json.dumps(error, ensure_ascii=False) + "\n")
+    else:
+        sys.stderr.write(render.render_error(error))
+
+
+def _content(args: argparse.Namespace) -> str | None:
+    if args.content is not None and args.content_file is not None:
+        raise SystemExit("use either --content or --content-file, not both")
+    if args.content_file is None:
+        return args.content
+    if args.content_file == "-":
+        return sys.stdin.read()
+    return Path(args.content_file).read_text(encoding="utf-8")
+
+
+def _cwd_path(value: str) -> str:
+    return str(Path(value).expanduser().absolute())
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # Global options are accepted before or after the subcommand.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("-w", "--workspace", default=argparse.SUPPRESS,
+                        help="workspace root (default: $MINDSLICE_WORKSPACE or nearest dir with mounts.toml)")
+    common.add_argument("--json", action="store_true", default=argparse.SUPPRESS,
+                        help="structured JSON output instead of human-readable text (errors too, on stderr)")
+    common.add_argument("--compact", action="store_true", default=argparse.SUPPRESS,
+                        help="single-line JSON output (implies --json)")
+    p = argparse.ArgumentParser(prog="mindslice", parents=[common],
+                                description="Layered, human-readable long-term memory for LLM agents.")
+    p.add_argument("--version", action="version", version=f"mindslice {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+    _add_parser = sub.add_parser
+    sub.add_parser = lambda *a, **kw: _add_parser(*a, parents=[common], **kw)  # type: ignore[method-assign]
+
+    s = sub.add_parser("init", help="create a workspace (mounts.toml, overlay/, staging/, slices/, .cache/)")
+    s.add_argument("path", nargs="?", default=".")
+
+    s = sub.add_parser("doctor", help="check local workspace, startup payload and MCP; guide client verification")
+
+    s = sub.add_parser("status", help="show mounts, pending review and unbaked overlay changes")
+
+    s = sub.add_parser("history", help="inspect recorded reasons and lifecycle events (not old content snapshots)")
+    s.add_argument("address", nargs="?", help="card address; omit for workspace history, including version switches")
+    s.add_argument("--limit", type=int, default=20)
+    s.add_argument("--offset", type=int, default=0)
+
+    s = sub.add_parser("explain", help="explain the sources, precedence and lineage of a read result")
+    s.add_argument("address")
+    s.add_argument("--follow", help="all | none | comma-separated roles/@aliases")
+    s.add_argument("--max-extensions", type=int, default=5)
+    s.add_argument("--extensions-offset", type=int, default=0)
+
+    s = sub.add_parser("rollback", help="preview and switch a mounted slice to an earlier directory; overlay stays")
+    s.add_argument("alias", type=normalize_alias)
+    s.add_argument("--to", dest="target", help="physical slice directory (default: recorded predecessor)")
+    s.add_argument("--dry-run", action="store_true")
+    s.add_argument("--yes", action="store_true", help="execute after reviewing the preview")
+
+    s = sub.add_parser("backup", help="create a verified portable directory snapshot, including external mounts")
+    s.add_argument("output", help="new backup directory outside the workspace and mounted sources")
+
+    s = sub.add_parser("restore", help="verify a backup and restore into a new workspace directory")
+    s.add_argument("source", help="backup directory")
+    s.add_argument("--output", required=True, help="new workspace directory; never overwrites an existing directory")
+
+    s = sub.add_parser("manifest", help="paginated mount and folder map for memory navigation")
+    s.add_argument("--limit", type=int, default=20)
+    s.add_argument("--offset", type=int, default=0)
+    s.add_argument("--max-folders", type=int, default=10, dest="max_folders_per_mount")
+    s.add_argument("--include-overview", action="store_true")
+    s.add_argument("--no-always", action="store_false", dest="include_always", help="omit the always-loaded cards")
+
+    s = sub.add_parser("boot", help="emit the session startup payload (instructions, standing cards and onboarding)")
+    s.add_argument("--cards-only", action="store_true", help="only standing card content, without startup instructions")
+
+    s = sub.add_parser("search", help="associative BM25 search returning card previews")
+    s.add_argument("query")
+    s.add_argument("--source", action="append", type=normalize_alias, help="restrict to mount alias; @ optional (repeatable)")
+    s.add_argument("--tag", action="append", dest="tags", help="require tag (repeatable, all must match)")
+    s.add_argument("-k", type=int, default=10)
+    s.add_argument("--offset", type=int, default=0)
+    s.add_argument("--max-neighbors", type=int, default=3)
+    s.add_argument("--follow", help="follow_supersedes: all (default) | none | comma-separated roles/@aliases")
+
+    s = sub.add_parser("read", help="exact resolution of an address (with lineage composition)")
+    s.add_argument("address", help="@alias/path, unambiguous alias/path, or relative card path (./path forces relative)")
+    s.add_argument("--follow", help="follow_supersedes: all (default) | none | comma-separated roles/@aliases")
+    s.add_argument("--max-backlinks", type=int, default=10)
+    s.add_argument("--backlinks-offset", type=int, default=0)
+    s.add_argument("--max-extensions", type=int, default=5)
+    s.add_argument("--extensions-offset", type=int, default=0)
+    s.add_argument("--markdown", action="store_true", help=argparse.SUPPRESS)  # deprecated: now the default
+
+    s = sub.add_parser("write", help="create/replace/append/delete a card in overlay/ (or staging/)")
+    s.add_argument("id", help="overlay-relative card id, e.g. api/auth-edge-cases")
+    s.add_argument("--op", choices=("create", "replace", "append", "delete"), default="create")
+    s.add_argument("--content", help="body text (append: bullet statements)")
+    s.add_argument("--content-file", help="read content from file ('-' = stdin)")
+    s.add_argument("--summary")
+    s.add_argument("--reason", help="why this change is needed; stored in engine history, not in the card")
+    s.add_argument("--title")
+    s.add_argument("--tag", action="append", dest="tags")
+    s.add_argument("--alias", action="append", dest="aliases")
+    s.add_argument("--extends", action="append")
+    s.add_argument("--supersedes", action="append")
+    s.add_argument("--load", choices=("always", "as-needed"),
+                   help="always = loaded into every session without a query (persona, language, standing instructions)")
+    s.add_argument("--stage", action="store_true", default=None,
+                   help="write to staging/ instead of overlay/ (default: only changes to always-loaded cards are staged)")
+    s.add_argument("--no-stage", action="store_false", dest="stage", help="write to overlay/ even if always-loaded")
+    s.add_argument("--if-match", help="sha256 the target must currently have")
+
+    s = sub.add_parser("mount", help="mount a read-only slice directory")
+    s.add_argument("path")
+    s.add_argument("--alias", type=normalize_alias, help="mount alias, with or without @")
+    s.add_argument("--precedence", type=int, default=50)
+    s.add_argument("--role", default="baseline")
+    s.add_argument("--keep-overlay", action="store_true",
+                   help="keep @overlay copies of this slice's cards (by default, unchanged exported copies are retired)")
+
+    s = sub.add_parser("unmount", help="remove a mount")
+    s.add_argument("alias", type=normalize_alias, help="mount alias, with or without @")
+
+    s = sub.add_parser("validate", help="lint the workspace or a slice directory")
+    s.add_argument("slice_path", nargs="?")
+    s.add_argument("--rebuild-index", action="store_true", help="rebuild .cache/index.sqlite with full sha256 verification")
+
+    s = sub.add_parser("bake", help="review and bake the workspace, or create/update one named slice")
+    s.add_argument("alias", nargs="?", type=normalize_alias, help="optional target alias; omit for workspace review")
+    s.add_argument("--assign", action="append", help="batch destination: CARD_OR_FOLDER=ALIAS (repeatable)")
+    s.add_argument("--defer", action="append", help="batch cards to leave in overlay: ID, folder/ or *")
+    s.add_argument("--plan", help="reviewed JSON plan from bake --dry-run --json")
+    s.add_argument("--fresh", action="store_true", help="ignore saved batch destination choices")
+    s.add_argument("--yes", action="store_true", help="execute a resolved batch plan without interactive confirmation")
+    s.add_argument("--output", help="slice directory or .zip/.tar.gz archive (default directory: "
+                   "slices/<name>.slice, or <name>-2.slice ...); the old folder is left as it was")
+    s.add_argument("--prefix", help="select overlay cards under this path; required for a new named target "
+                   "(default for an existing alias: cards that extend, supersede or share a path with its cards)")
+    s.add_argument("--tag", action="append", dest="tags", help="bake the overlay cards with this tag (repeatable)")
+    s.add_argument("--include-deps", action="store_true", help="also bake overlay cards the selection references")
+    s.add_argument("--dry-run", action="store_true", help="show what would move, write nothing")
+    s.add_argument("--name", help="slice name")
+    s.add_argument("--description", help="slice description")
+    s.add_argument("--slice-version", help="version (default: 0.1.0 for a new slice, patch bump for an update)")
+
+    s = sub.add_parser("diff", help="show staged changes (or overlay overrides)")
+    s.add_argument("--scope", choices=("staging", "overlay"), default="staging")
+
+    for command, description in (
+        ("apply", "accept selected staging cards (default: all), saved and active immediately"),
+        ("discard", "reject selected staging cards (default: all), keeping live memory unchanged"),
+        ("review", "interactively accept, reject or leave staged cards pending"),
+    ):
+        s = sub.add_parser(command, help=description)
+        s.add_argument("ids", nargs="*", help="exact pending card IDs or @overlay/path; omit for all")
+
+    s = sub.add_parser("mcp", help="serve the 4-tool MCP server (manifest/search/read/write) over stdio")
+    s.add_argument("--stage-writes", action="store_true", help="force every agent write into staging/")
+    return p
+
+
+def _open(args: argparse.Namespace) -> Workspace:
+    root = args.workspace or os.environ.get("MINDSLICE_WORKSPACE")
+    return Workspace(root) if root else Workspace.discover()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    from .mcp_server import ensure_utf8_stdio
+
+    ensure_utf8_stdio()  # output is UTF-8 (CJK-safe) regardless of the console locale
+    args = build_parser().parse_args(argv)
+    args.workspace = getattr(args, "workspace", None)
+    args.compact = getattr(args, "compact", False)
+    args.json = getattr(args, "json", False) or args.compact
+    try:
+        if args.command == "init":
+            target = Path(args.workspace or args.path)
+            with Workspace.init(target) as ws:
+                _output(args, {"workspace": str(ws.root), "mounts": str(ws.root / "mounts.toml")}, render.render_init)
+            return 0
+        if args.command == "restore":
+            _output(args, Workspace.restore(args.source, args.output), _render_restore)
+            return 0
+        if args.command == "doctor":
+            from .doctor import diagnose, render as render_doctor
+
+            result = diagnose(args.workspace or os.environ.get("MINDSLICE_WORKSPACE"))
+            _output(args, result, render_doctor)
+            return 0 if result["ok"] else 1
+        if args.command == "mcp":
+            from .mcp_server import serve
+
+            with _open(args) as ws:
+                serve(ws, stage_writes=args.stage_writes)
+            return 0
+        with _open(args) as ws:
+            return _dispatch(ws, args)
+    except ApplyConflictError as exc:
+        _error(args, exc.to_dict())
+        return 2
+    except MindSliceError as exc:
+        _error(args, exc.to_dict())
+        return 1
+    except (ValueError, TypeError, OSError) as exc:
+        _error(args, {"error": type(exc).__name__, "message": str(exc)})
+        return 1
+
+
+def _render_restore(result: dict[str, Any]) -> str:
+    lines = [f"Restored workspace: {result['workspace']}", result["note"]]
+    lines += [f"Historical version unavailable in backup: {path}" for path in result["unavailable_versions"]]
+    return "\n".join(lines) + "\n"
+
+
+def _render_backup(result: dict[str, Any]) -> str:
+    lines = [f"Backup: {result['path']} ({result['files']} files)", result["note"]]
+    lines += [f"Historical version already missing: {path}" for path in result["unavailable_versions"]]
+    return "\n".join(lines) + "\n"
+
+
+def _dispatch(ws: Workspace, args: argparse.Namespace) -> int:
+    cmd = args.command
+
+    def out(data: Any, renderer: render.Renderer) -> None:
+        _output(args, data, renderer)
+
+    if cmd == "status":
+        out(ws.status(), render_status)
+    elif cmd in ("history", "explain"):
+        from ..operations.audit import render_history, render_explain
+        with ws._reading():
+            address = cli_reference(ws, args.address) if args.address else None
+            result = (ws.card_history(address, args.limit, args.offset) if cmd == "history" else
+                      ws.explain(address, _follow(args.follow), args.max_extensions, args.extensions_offset))
+        out(result, render_history if cmd == "history" else render_explain)
+    elif cmd == "backup":
+        out(ws.backup(args.output), _render_backup)
+    elif cmd == "rollback":
+        from ..operations.recovery import render_rollback
+        from ..errors import RecoveryError
+        plan = ws.rollback(args.alias, args.target, dry_run=True)
+        if args.dry_run:
+            out(plan, render_rollback)
+            return 0 if plan["ready"] else 1
+        if not plan["ready"]:
+            raise RecoveryError("rollback is blocked; inspect rollback --dry-run", plan=plan)
+        if not args.yes:
+            if args.json or not sys.stdin.isatty():
+                raise RecoveryError("review rollback --dry-run, then use --yes to execute", plan=plan)
+            sys.stderr.write(render_rollback(plan) + "Switch this slice pointer? [yes/No]: ")
+            sys.stderr.flush()
+            try:
+                answer = sys.stdin.readline().strip().lower()
+            except KeyboardInterrupt:
+                answer = ""
+            if answer not in ("yes", "y"):
+                out({"cancelled": True}, render.render_cancelled)
+                return 0
+        result = ws.rollback(args.alias, plan["path"], revision=plan["revision"])
+        out(result, lambda r: "Slice pointer switched.\n" + render_rollback(r))
+    elif cmd == "manifest":
+        out(ws.manifest(args.limit, args.offset, args.max_folders_per_mount, args.include_overview,
+                        args.include_always), render.render_manifest)
+    elif cmd == "boot":
+        from .mcp_server import format_instructions
+
+        result = ws.boot()
+        if args.json:
+            if args.cards_only:
+                _emit({"cards": result["cards"], "total": result["total"]}, args.compact)
+            else:
+                _emit(dict(result, instructions=format_instructions(result)), args.compact)
+        else:
+            text = render_boot(result["cards"], header="") if args.cards_only else format_instructions(result)
+            if text:
+                sys.stdout.write(text if text.endswith("\n") else text + "\n")
+        for item in result.get("pending_approval", []):
+            sys.stderr.write(f"awaiting approval: {ws.table().overlay.alias}/{item['id']} ({item['reason']}); "
+                             "review with `mindslice diff`, approve with `mindslice apply`\n")
+    elif cmd == "search":
+        out(ws.search(args.query, args.source, args.tags, args.k, args.offset, args.max_neighbors, _follow(args.follow)),
+            render.render_search)
+    elif cmd == "read":
+        with ws._reading():
+            address = cli_reference(ws, args.address)
+            result = ws.read(address, _follow(args.follow), args.max_backlinks, args.backlinks_offset,
+                             args.max_extensions, args.extensions_offset)
+        out(result, render.render_read)
+    elif cmd == "write":
+        content = _content(args)
+        with ws._writing() as table:
+            extends = [cli_reference(ws, ref, source=table.overlay.alias) for ref in args.extends] if args.extends else None
+            supersedes = [cli_reference(ws, ref, source=table.overlay.alias) for ref in args.supersedes] if args.supersedes else None
+            result = ws.write(args.id, args.op, content, args.summary, args.title, args.tags, args.aliases,
+                              extends, supersedes, args.stage, args.if_match, args.load, args.reason)
+        out(result, render.render_write)
+    elif cmd == "mount":
+        out(ws.mount(_cwd_path(args.path), args.alias, args.precedence, args.role,
+                     retire_overlay=not args.keep_overlay), render.render_mount)
+    elif cmd == "unmount":
+        out(ws.unmount(args.alias), render.render_unmount)
+    elif cmd == "validate":
+        result = ws.validate(_cwd_path(args.slice_path) if args.slice_path else None, args.rebuild_index)
+        out(result, render.render_validate)
+        return 0 if result["ok"] else 1
+    elif cmd == "bake":
+        if args.alias is None:
+            from .bake_review import run
+            return run(ws, args, out)
+        if args.assign or args.defer or args.plan or args.fresh:
+            from ..errors import InvalidArgumentsError
+            raise InvalidArgumentsError("batch review options cannot be combined with a target alias")
+        out(ws.bake(args.alias, _cwd_path(args.output) if args.output else None, args.prefix, args.tags,
+                    args.include_deps, args.dry_run, name=args.name, description=args.description,
+                    version=args.slice_version), render.render_bake)
+    elif cmd == "diff":
+        result = ws.diff(args.scope)
+        if args.json:
+            _emit(result, args.compact)
+        else:
+            sys.stdout.write("".join(item["diff"] for item in result["items"]))
+            for item in result["items"]:
+                for change in item.get("changes", []):
+                    if change.get("reason"):
+                        sys.stderr.write(f"reason: {item['address']} ({change['op']}): {change['reason']}\n")
+                if item.get("conflict"):
+                    sys.stderr.write(f"conflict: {item['address']}: {item['conflict']}\n")
+    elif cmd == "apply":
+        out(ws.apply(args.ids or None), render.render_apply)
+    elif cmd == "discard":
+        out(ws.discard(args.ids or None), render.render_discard)
+    elif cmd == "review":
+        from .staging_review import run
+        out(run(ws, args.ids or None), render.render_review)
+    else:  # pragma: no cover - argparse guards this
+        raise SystemExit(f"unknown command {cmd}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

mindslice/interfaces/cli_addressing.py

@@ -0,0 +1,52 @@
+"""CLI shorthand only; persisted card references and the Python/MCP APIs keep their own scopes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..model.addressing import format_address, normalize_alias, normalize_path, parse_address
+from ..errors import AmbiguousAddressError, InvalidAddressError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..workspace import Workspace
+
+
+def reference(ws: "Workspace", value: str, *, source: str | None = None) -> str:
+    """Normalize a CLI reference under the caller's workspace lock.
+
+    ``source=None`` is a global read; lineage arguments to write use the overlay as source.
+    ``./path`` explicitly chooses the relative interpretation. An existing ``alias/path`` target
+    is qualified only when no relative target also exists in that operation's scope.
+    """
+    raw = value.strip()
+    if raw.startswith("@"):
+        alias, path = parse_address(raw)
+        return format_address(alias, path)
+    if raw.startswith(("./", ".\\")):
+        return normalize_path(raw)
+    head, sep, tail = raw.partition("/")
+    if not sep:
+        return raw
+    try:
+        alias = normalize_alias(head)
+    except InvalidAddressError:
+        return raw
+    cats = ws.index.catalogs()
+    target = cats[alias].lookup(tail) if alias in cats else None
+    if target is None:
+        return raw
+    path = normalize_path(raw)
+    if source is None:
+        local = ws.index.cards_at_path(path) or ws.index.cards_with_alias(path)
+        relative = [format_address(r["mount"], r["path"]) for r in local]
+    else:
+        local = cats[source].lookup(raw) if source in cats else None
+        relative = [format_address(source, local)] if local is not None else []
+    qualified = format_address(alias, target)
+    if relative:
+        raise AmbiguousAddressError(
+            f"{value!r} matches both a relative card and {qualified}; "
+            f"use {qualified!r} for the mount or {'./' + raw!r} for the relative path",
+            address=value, qualified=qualified, relative=relative,
+        )
+    return qualified

mindslice/interfaces/doctor.py

@@ -0,0 +1,184 @@
+"""Local diagnostics and a truthful handoff to client-side session verification."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import sqlite3
+import subprocess
+import sys
+
+from .. import __version__
+from ..errors import MindSliceError
+from ..workspace import Workspace
+from .mcp_server import DOCTOR_CLIENT, format_instructions, read_clients
+
+
+# What only the connected app can show. Self-contained: a pip-installed user has no docs checkout to open.
+CLIENT_STEPS = [
+    "Restart or reconnect the app so it reloads its MCP configuration, open a conversation, and run doctor again: "
+    "client_connection should name the app. It should list this server with four tools: manifest, search, read, write.",
+    "Give the startup check a phrase the model cannot guess. Save a temporary standing card with words you make up: "
+    "mindslice -w <workspace> write setup-check/startup --load always --no-stage "
+    "--summary \"The MindSlice startup check phrase is amber maple 47.\" --reason \"Temporary setup check.\"",
+    "Start a new conversation (a one-shot, non-interactive session from the shell if the app has one) and send only: "
+    "\"What is the MindSlice startup check phrase? Answer from what you were given for this session; do not search "
+    "or read memory for it. Say NONE if you do not have it.\" The phrase means standing memory reaches the model; "
+    "NONE, or a search or read call, means it does not: fix how the app delivers it, then ask again in another new "
+    "conversation.",
+    "Remove the card: mindslice -w <workspace> write setup-check/startup --op delete --no-stage "
+    "--reason \"Setup check complete.\"",
+    "Ask about a fact already saved in memory without repeating it. The answer should come from an actual "
+    "search or read call that returns the card.",
+    "Let the app compact a long conversation (or trigger compaction if it has a command), then ask for the "
+    "standing instructions again. They should still be there.",
+    "Go by the app's tool-call or hook log where it has one; the model saying it remembers is not proof.",
+]
+
+# Apps that pass MCP server instructions to the model may cut them at a length (a few thousand characters), and
+# the standing cards are the end of that text. Above this size, say so.
+INSTRUCTIONS_SOFT_LIMIT = 4000
+
+
+def probe_mcp(root):
+    """Exercise the real stdio entry point; never execute commands from client configs."""
+    command = [sys.executable, "-m", "mindslice", "-w", str(root), "mcp"]
+    requests = [
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
+            "protocolVersion": "2025-06-18", "capabilities": {},
+            "clientInfo": {"name": DOCTOR_CLIENT, "version": __version__}}},
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+        {"jsonrpc": "2.0", "id": 3, "method": "tools/call",
+         "params": {"name": "manifest", "arguments": {"limit": 1}}},
+    ]
+    result = subprocess.run(command, input="".join(json.dumps(r) + "\n" for r in requests),
+                            capture_output=True, text=True, encoding="utf-8", timeout=10)
+    if result.returncode:
+        raise ValueError(f"MCP exited with status {result.returncode}: {result.stderr.strip()[:500]}")
+    messages = [json.loads(line) for line in result.stdout.splitlines()]
+    if any(not isinstance(r, dict) for r in messages):
+        raise ValueError("MCP returned an invalid JSON-RPC response")
+    replies = {r.get("id"): r for r in messages}
+    if any(not isinstance(replies.get(i, {}).get("result"), dict) for i in (1, 2, 3)):
+        raise ValueError("MCP did not return successful initialize, tools/list and manifest responses")
+    if not replies[1]["result"].get("instructions"):
+        raise ValueError("MCP startup instructions are empty")
+    names = {t["name"] for t in replies[2]["result"].get("tools", [])}
+    if names != {"manifest", "search", "read", "write"} or replies[3]["result"].get("isError"):
+        raise ValueError("MCP tools or manifest call failed validation")
+    contents = replies[3]["result"].get("content", [])
+    manifest = next((json.loads(c["text"]) for c in contents if c.get("type") == "text"), None)
+    if not isinstance(manifest, dict) or not isinstance(manifest.get("mounts"), list):
+        raise ValueError("MCP manifest response did not contain a mount list")
+    return command
+
+
+def diagnose(root=None):
+    checks = []
+
+    def add(name, status, message, action=None, **details):
+        checks.append(dict(name=name, status=status, message=message,
+                           **({"action": action} if action else {}), **details))
+
+    add("runtime", "pass" if sys.version_info >= (3, 12) else "fail",
+        f"MindSlice {__version__}; Python {sys.version.split()[0]}; SQLite {sqlite3.sqlite_version}")
+    try:
+        with sqlite3.connect(":memory:") as conn:
+            conn.execute("CREATE VIRTUAL TABLE probe USING fts5(text)")
+        add("fts5", "pass", "SQLite FTS5 is available")
+    except sqlite3.Error as exc:
+        add("fts5", "fail", str(exc), "Use a Python installation with SQLite FTS5 enabled.")
+
+    ws = None
+    try:
+        ws = Workspace(root, lock_timeout=3) if root else Workspace.discover(lock_timeout=3)
+        root = str(ws.root)
+        table = ws.table()
+        add("workspace", "pass", root)
+        missing = [m.alias for m in table.all() if not m.root.is_dir()]
+        add("mounts", "fail" if missing else "pass",
+            "Missing directories: " + ", ".join(missing) if missing else f"{len(table.mounts)} mounted slice(s)",
+            "Restore the directories or unmount the missing slices." if missing else None)
+        try:
+            validation = ws.validate()
+            with ws._reading():
+                integrity = [row[0] for row in ws.index.conn.execute("PRAGMA quick_check")]
+            if integrity != ["ok"]:
+                raise sqlite3.DatabaseError("; ".join(integrity))
+            add("index", "pass", "Index synchronized; SQLite integrity check passed")
+            add("cards", "fail" if validation["errors"] else ("warn" if validation["warnings"] else "pass"),
+                f"{len(validation['errors'])} error(s), {len(validation['warnings'])} warning(s)",
+                "Run mindslice -w <workspace> validate for card and reference details."
+                if validation["errors"] or validation["warnings"] else None,
+                errors=validation["errors"], warnings=validation["warnings"])
+        except (MindSliceError, OSError, ValueError, sqlite3.Error) as exc:
+            add("index", "fail", str(exc),
+                "Run mindslice -w <workspace> validate --rebuild-index. Preserve overlay/, staging/ and .history/.")
+        try:
+            boot = ws.boot()
+            payload = format_instructions(boot)
+            long = boot["total"] and len(payload) > INSTRUCTIONS_SOFT_LIMIT
+            add("boot", "pass", f"{boot['total']} standing card(s); {len(payload)} characters in startup payload",
+                standing_cards=boot["total"], payload_characters=len(payload),
+                **({"note": "An app that passes MCP server instructions to the model may cut them at a few thousand "
+                            "characters, and the standing cards come last. Do not count on server instructions alone "
+                            "for a payload this long: the session-start hook or the manifest rule delivers it whole."}
+                   if long else {}))
+            if boot.get("pending_approval"):
+                add("standing_review", "warn", "Some standing-card changes are still pending, not active",
+                    "Run mindslice -w <workspace> review.")
+        except (MindSliceError, OSError, ValueError, sqlite3.Error) as exc:
+            add("boot", "fail", str(exc), "Resolve workspace errors, then run mindslice -w <workspace> boot.")
+        # No workspace lock is held while the subprocess acquires its own lock.
+        try:
+            command = probe_mcp(ws.root)
+            add("mcp", "pass", "Stdio initialize, four tools and manifest succeeded", command=command)
+        except (OSError, ValueError, KeyError, TypeError, AttributeError, subprocess.SubprocessError) as exc:
+            add("mcp", "fail", str(exc),
+                "Check the Python executable and workspace path in the app's MCP configuration.")
+    except (MindSliceError, OSError, ValueError, sqlite3.Error) as exc:
+        add("workspace", "fail", str(exc),
+            "Use mindslice -w /path/to/workspace doctor, or create a workspace with mindslice init /path/to/workspace.")
+    finally:
+        if ws is not None:
+            ws.close()
+    clients = read_clients(root) if root and ws is not None else {}
+    if clients:
+        name, last = max(clients.items(), key=lambda item: str(item[1].get("connected_at", "")))
+        used = [t for t in last.get("tools_used", []) if isinstance(t, str)]
+        others = sorted(n for n in clients if n != name)
+        add("client_connection", "pass",
+            f"{name}{' ' + last['version'] if isinstance(last.get('version'), str) else ''} started this "
+            f"workspace's MCP server at {last.get('connected_at', 'an unknown time')}; "
+            + (f"first tool call: {last.get('first_tool')}; tools used: {', '.join(used)}" if used else "no tool call yet")
+            + (f"; earlier: {', '.join(others)}" if others else ""),
+            note="This shows an app launches the server. It does not show the model received the startup payload.",
+            clients=clients)
+    elif ws is not None:
+        add("client_connection", "pending", "No app has started this workspace's MCP server yet",
+            "Restart or reconnect the app, open a conversation and run doctor again. If this stays empty, the app's "
+            "MCP entry is not loaded or points at another workspace.")
+    add("client_session", "manual", "Client configuration and model receipt have not been verified",
+        "Confirm these in the app itself; a local MCP success does not prove the app loads memory into the model.",
+        steps=CLIENT_STEPS)
+    return {"ok": not any(c["status"] == "fail" for c in checks), "scope": "local_engine",
+            "workspace": str(root) if root else None, "client_connected": bool(clients), "client_verified": False,
+            "checks": checks}
+
+
+def render(result):
+    title = "Local checks passed" if result["ok"] else "Local checks need attention"
+    lines = [title + "; client session verification is still required.", ""]
+    workspace = result["workspace"] or "/path/to/workspace"
+    quoted = subprocess.list2cmdline([workspace]) if os.name == "nt" else shlex.quote(workspace)
+    for check in result["checks"]:
+        lines.append(f"[{check['status'].upper()}] {check['name']}: {check['message']}")
+        if check.get("action"):
+            lines.append("  Next: " + check["action"].replace("<workspace>", quoted))
+        if check.get("note"):
+            lines.append("  Note: " + check["note"])
+        for number, step in enumerate(check.get("steps", []), 1):
+            lines.append(f"    {number}. " + step.replace("<workspace>", quoted))
+    return "\n".join(lines) + "\n"