fix(ux): MCP tool errors set isError; add `sibyl migrate --force`

bugflow 2026-06-05 (UX focus). Two reporter-sourced gaps, both verified.

sibyl-memory-mcp 0.1.6 -> 0.1.7
_err() returned a plain dict, so FastMCP delivered tool errors as SUCCESSFUL
results (isError:false) with the error nested inside the payload. Agents
keying off the protocol-level isError flag could not detect failures. _err()
now raises ToolError carrying the same structured payload as JSON
(isError:true; error/code/recovery/upgrade_url preserved). Tool signatures
unchanged; only the error envelope is corrected.

sibyl-memory-cli 0.3.11 -> 0.3.12
`sibyl migrate` had no --force flag, so a detected harness already holding a
non-sibyl memory provider dead-ended at "Use --force to overwrite." with no
flag to pass. Added --force, threaded cli -> run_guided_setup(force=) ->
wire(force=force).

Tests: 34 green (16 mcp + 4 new mcp regression + migrate suite + 2 new cli
force-threading). 10 pre-existing CodexWirer/ClaudeWirer config-format failures
in setup.py are unrelated (that file is untouched by this change).

sibyl-memory-cli/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `sibyl-memory-cli` are recorded here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows
 [SemVer](https://semver.org/).
 
+## [0.3.12] — 2026-06-05
+
+### Fixed
+
+- **`sibyl migrate --force` (onboarding dead-end).** When a detected harness
+  already had a non-sibyl memory provider, the wirer refused with
+  "Use --force to overwrite." but `run_guided_setup` called `wire()` with no
+  `force`, and `sibyl migrate` had no `--force` flag to pass, leaving the user
+  with no way forward. Added `--force` to `sibyl migrate`, threaded through
+  `cmd_migrate` → `run_guided_setup(force=)` → `wire(force=force)`, so migration
+  can overwrite an existing provider when the user explicitly opts in.
+  Regression coverage: `tests/test_migrate_force_2026_06_05.py`. (bugflow)
+
 ## [0.3.11] — 2026-06-01
 
 ### Fixed

sibyl-memory-cli/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sibyl-memory-cli"
-version = "0.3.11"
+version = "0.3.12"
 description = "Command-line interface for the Sibyl Memory Plugin. `sibyl init` activates, `sibyl upgrade` runs the staker / subscription flow, `sibyl status` shows current tier and DB stats, `sibyl whoami` gives a one-line account summary, `sibyl devices` lists active devices and supports per-device revoke."
 authors = [{ name = "SIBYL, Sibyl Labs LLC", email = "sibyl@sibyllabs.org" }]
 license = { text = "MIT" }

sibyl-memory-cli/src/sibyl_memory_cli/cli.py

@@ -1056,7 +1056,7 @@ def cmd_migrate(args: argparse.Namespace) -> int:
     io = _migrate_io()
     report = M.run_guided_setup(
         home=home, cwd=cwd, db_path=db_path, backup_parent=backup_parent,
-        io=io, debloat=not args.no_debloat,
+        io=io, debloat=not args.no_debloat, force=getattr(args, "force", False),
     )
 
     ph = report.get("phases", {})
@@ -1196,6 +1196,11 @@ def build_parser() -> argparse.ArgumentParser:
         "--yes", "-y", action="store_true",
         help="Skip the initial confirm (the trim step still always asks separately)",
     )
+    p_migrate.add_argument(
+        "--force", action="store_true",
+        help="Overwrite an existing non-sibyl memory provider when wiring a harness "
+             "(without this, migrate stops at that harness and tells you to re-run with --force)",
+    )
     p_migrate.set_defaults(func=cmd_migrate)
 
     return p

sibyl-memory-cli/src/sibyl_memory_cli/migrate.py

@@ -330,7 +330,7 @@ class GuidedIO:
 def run_guided_setup(*, home=None, cwd=None, db_path=None, backup_parent=None,
                      io: Optional[GuidedIO] = None, wirers: Optional[dict] = None,
                      extract_fn: Optional[Callable[[Path, Path], None]] = None,
-                     debloat: bool = True, now=None) -> dict:
+                     debloat: bool = True, force: bool = False, now=None) -> dict:
     """The assembled guided flow: backup -> auto-wire each harness (instructions on
     failure) -> extraction handoff -> verify -> confirmed debloat. Returns a structured
     report. `extract_fn(backup_dir, db_path)` performs/simulates extraction; default
@@ -367,7 +367,7 @@ def run_guided_setup(*, home=None, cwd=None, db_path=None, backup_parent=None,
         if w.current_state().get("wired_with_sibyl"):
             wire_report[name] = "already"
             continue
-        outcome = w.wire()
+        outcome = w.wire(force=force)
         wire_report[name] = outcome.status
         if outcome.status not in ("wired", "already"):
             io.say(f"{name}: auto-wire incomplete ({outcome.message}). Do this manually:")

sibyl-memory-cli/tests/test_migrate_force_2026_06_05.py

@@ -0,0 +1,67 @@
+"""Regression (bugflow 2026-06-05): `sibyl migrate --force` must reach the wirers.
+
+Onboarding dead-end: when a detected harness already had a non-sibyl memory
+provider, the wirer refused with "Use --force to overwrite." but
+`run_guided_setup` called `wire()` with no `force`, and `sibyl migrate` had no
+`--force` flag to pass. The flag now threads cli -> run_guided_setup(force=) ->
+wire(force=force).
+"""
+from __future__ import annotations
+
+from sibyl_memory_cli import migrate as M
+from sibyl_memory_cli.setup import WireOutcome
+from sibyl_memory_client import MemoryClient
+
+
+class _RecordingWirer:
+    """A fake harness wirer that records the `force` kwarg it was called with."""
+
+    name = "rec"
+
+    def __init__(self):
+        self.seen_force = None
+
+    def is_present(self):
+        return True
+
+    def current_state(self):
+        return {"wired_with_sibyl": False}
+
+    def wire(self, *, force: bool = False, dry_run: bool = False, prompt_fn=None):
+        self.seen_force = force
+        return WireOutcome(self.name, "wired", "ok")
+
+
+def _home_with_memory(tmp_path):
+    h = tmp_path / "home"
+    (h / "proj").mkdir(parents=True)
+    (h / "proj" / "CLAUDE.md").write_text("# memory\n- a fact worth keeping\n")
+    db = h / ".sibyl-memory" / "memory.db"
+    db.parent.mkdir(parents=True)
+    return h, db
+
+
+def _fake_extract(_backup_dir, db_path):
+    MemoryClient.local(str(db_path), tenant_id="qa").set_entity("f", "a", {"v": 1})
+
+
+def test_force_true_threads_to_wirer(tmp_path):
+    h, db = _home_with_memory(tmp_path)
+    rec = _RecordingWirer()
+    M.run_guided_setup(
+        home=h, cwd=h / "proj", db_path=db, backup_parent=tmp_path / "bk",
+        io=M.GuidedIO(scripted=["n"]), wirers={"rec": rec},
+        extract_fn=_fake_extract, force=True,
+    )
+    assert rec.seen_force is True
+
+
+def test_force_defaults_false(tmp_path):
+    h, db = _home_with_memory(tmp_path)
+    rec = _RecordingWirer()
+    M.run_guided_setup(
+        home=h, cwd=h / "proj", db_path=db, backup_parent=tmp_path / "bk",
+        io=M.GuidedIO(scripted=["n"]), wirers={"rec": rec},
+        extract_fn=_fake_extract,
+    )
+    assert rec.seen_force is False

sibyl-memory-mcp/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `sibyl-memory-mcp` are recorded here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows
 [SemVer](https://semver.org/).
 
+## [0.1.7] - 2026-06-05
+
+### Fixed
+
+- **Tool errors now set the MCP `isError` flag (agent error-detection).**
+  `_err()` previously returned a plain dict, which FastMCP delivered as a
+  *successful* tool result (`isError: false`) with the error nested inside the
+  payload, so an agent keying off the protocol-level `isError` flag could not
+  detect the failure at all. `_err()` now raises `ToolError` carrying the same
+  structured payload encoded as JSON, so callers both (a) see `isError: true`
+  and (b) can still parse `error`/`code`/`recovery`/`upgrade_url` from the
+  message. No tool signatures change; only the error envelope is corrected.
+  Regression coverage: `tests/test_err_toolerror_2026_06_05.py`. (bugflow)
+
 ## [0.1.6] - 2026-06-04
 
 ### Added

sibyl-memory-mcp/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sibyl-memory-mcp"
-version = "0.1.6"
+version = "0.1.7"
 description = "MCP server for Sibyl Memory Plugin: wraps the local SQLite + FTS5 memory engine and exposes it to MCP-compatible agents (Claude Code, Codex, Cursor, Continue, anything that speaks MCP)."
 readme = "README.md"
 requires-python = ">=3.10"

sibyl-memory-mcp/src/sibyl_memory_mcp/server.py

@@ -35,9 +35,10 @@ import os
 import re
 import threading
 from pathlib import Path
-from typing import Any
+from typing import Any, NoReturn
 
 from mcp.server.fastmcp import FastMCP
+from mcp.server.fastmcp.exceptions import ToolError
 from sibyl_memory_client import DEFAULT_TENANT, MemoryClient
 from sibyl_memory_client.exceptions import (
     CapExceededError,
@@ -166,8 +167,16 @@ def _build_client() -> MemoryClient:
 # Error mapping
 # ----------------------------------------------------------------------
 
-def _err(e: Exception) -> dict[str, Any]:
-    """Map SDK exception → structured error payload the agent can reason about."""
+def _err(e: Exception) -> NoReturn:
+    """Map an SDK exception to a ToolError so the MCP envelope sets isError=true.
+
+    Previously this returned a plain dict, which FastMCP delivered as a
+    SUCCESSFUL tool result (isError=false) with the error nested inside the
+    payload. An agent keying off the protocol-level isError flag could not
+    detect the failure at all. We now raise ToolError carrying the same
+    structured payload encoded as JSON, so callers both (a) see isError=true
+    and (b) can still parse error/code/recovery/upgrade_url from the message.
+    """
     cls = type(e).__name__
     payload = {"error": cls, "message": str(e)}
     if isinstance(e, CapExceededError):
@@ -184,7 +193,7 @@ def _err(e: Exception) -> dict[str, Any]:
         payload["code"] = "NOT_FOUND"
     elif isinstance(e, ValidationError):
         payload["code"] = "VALIDATION_ERROR"
-    return payload
+    raise ToolError(json.dumps(payload, ensure_ascii=False))
 
 
 def _coerce_body(body: Any) -> Any:

sibyl-memory-mcp/tests/test_err_toolerror_2026_06_05.py

@@ -0,0 +1,54 @@
+"""Regression (bugflow 2026-06-05): tool errors must set the MCP `isError` flag.
+
+`_err()` used to return a plain dict, which FastMCP delivered as a *successful*
+tool result (`isError: false`) with the error nested inside the payload — an
+agent keying off the protocol-level `isError` flag could not detect the failure
+at all. `_err()` now raises `ToolError` carrying the same structured payload as
+JSON, so callers see `isError: true` AND can still parse error/code/recovery.
+"""
+from __future__ import annotations
+
+import json
+
+import pytest
+from mcp.server.fastmcp.exceptions import ToolError
+
+import sibyl_memory_mcp.server as server
+from sibyl_memory_client.exceptions import (
+    CapExceededError,
+    NotFoundError,
+    TierGateError,
+    ValidationError,
+)
+
+
+def test_err_raises_toolerror_not_returns_dict():
+    # The whole point of the fix: _err raises rather than returns.
+    with pytest.raises(ToolError):
+        server._err(NotFoundError("entity not found"))
+
+
+@pytest.mark.parametrize(
+    "exc, code",
+    [
+        (CapExceededError("over the 2 MB free-tier cap", current_size=3_000_000, cap=2_000_000), "CAP_EXCEEDED"),
+        (TierGateError("paid feature", feature="self_learning"), "TIER_GATED"),
+        (NotFoundError("missing"), "NOT_FOUND"),
+        (ValidationError("bad body"), "VALIDATION_ERROR"),
+    ],
+)
+def test_err_toolerror_preserves_structured_payload(exc, code):
+    with pytest.raises(ToolError) as ei:
+        server._err(exc)
+    payload = json.loads(str(ei.value))
+    assert payload["code"] == code
+    assert payload["error"] == type(exc).__name__
+    assert payload["message"]  # non-empty human message survives
+
+
+def test_cap_exceeded_keeps_recovery_and_upgrade_url():
+    with pytest.raises(ToolError) as ei:
+        server._err(CapExceededError("cap", current_size=3_000_000, cap=2_000_000))
+    payload = json.loads(str(ei.value))
+    assert "Run `sibyl upgrade`" in payload["recovery"]
+    assert payload["upgrade_url"].startswith("https://")