fix(cli): report missing notes with a failing exit status

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/cli/commands/tool.py

@@ -770,14 +770,11 @@ def read_note(
                 )
             )
 
-        # MCP tool returns an error field on failure in JSON mode (e.g.
-        # SECURITY_VALIDATION_ERROR on a path-traversal identifier). A genuine
-        # not-found returns null fields with no `error` key, so it still exits 0.
-        # Trigger: result carries a non-empty `error`.
-        # Why: parity with edit-note/delete-note/search-notes so a blocked read
-        #      surfaces a non-zero exit instead of looking like success.
-        # Outcome: print the error to stderr and exit non-zero.
-        if isinstance(result, dict) and result.get("error"):
+        # A missing note may carry useful suggestions. Render those in the
+        # requested mode before exiting non-zero; other failures keep the
+        # existing JSON diagnostic path.
+        not_found = isinstance(result, dict) and result.get("error") == "NOTE_NOT_FOUND"
+        if isinstance(result, dict) and result.get("error") and not not_found:
             typer.echo(f"Error: {result['error']}", err=True)
             _print_json(result)
             raise typer.Exit(1)
@@ -801,9 +798,12 @@ def read_note(
             else:
                 console.print(Text(text))
         elif mode == "plain":
-            _plain_read_note(result, include_frontmatter=include_frontmatter)
+            _plain_read_note(result, include_frontmatter=include_frontmatter and not not_found)
         else:
             _display_read_note(result, include_frontmatter=include_frontmatter)
+        if not_found:
+            typer.echo(f"Error: Note not found: {identifier}", err=True)
+            raise typer.Exit(1)
     except ValueError as e:
         typer.echo(f"Error: {e}", err=True)
         raise typer.Exit(1)

src/basic_memory/man/man3/read-note(3).md

@@ -37,10 +37,13 @@ bm tool read-note IDENTIFIER [--project NAME | --project-id UUID]
 
 Returns the raw markdown of a note. The identifier is resolved through a
 cascade: direct permalink lookup, then exact title match, then full-text
-search. If nothing matches exactly, read-note returns guidance text instead
-of an error: a ranked list of related notes, each with a copy-pasteable
+search. If nothing matches exactly, MCP text mode returns guidance:
+a ranked list of related notes, each with a copy-pasteable
 `read_note()` call, plus suggested `search_notes()` and `write_note()` next
-steps. A miss is a navigable dead end, not an exception.
+steps. JSON mode returns null note fields plus `error: "NOTE_NOT_FOUND"`,
+a message naming the identifier, and `related_results` when available.
+The CLI exits with status 1 for a missing note in every output mode, retaining
+suggestions in JSON, plain, and Rich output. An existing empty note still succeeds.
 
 Accepted identifier forms (all verified):
 
@@ -56,7 +59,7 @@ Accepted identifier forms (all verified):
 - **project_id** (string | null, optional, default: None) — Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects().
 - **page** (integer, optional, default: 1) — Page of fallback-search results to use when the identifier does not resolve to a note directly (default: 1). A direct or exact-title match returns the note content — page/page_size never chunk the note itself, and the title-match lookup pages through fixed-size pages of title results until an exact match is found or results are exhausted, regardless of page or page_size. Aliases: page_number.
 - **page_size** (integer, optional, default: 10) — Number of fallback-search results per page (default: 10). When no match is found, this caps how many related-note suggestions are listed. Aliases: limit, per_page.
-- **output_format** (string, optional, default: "text") — "text" returns markdown content or guidance text. "json" returns a structured object with title/permalink/file_path/content/frontmatter.
+- **output_format** (string, optional, default: "text") — "text" returns markdown content or guidance text. "json" returns a structured object with title/permalink/file_path/content/frontmatter. Unresolved notes carry error="NOTE_NOT_FOUND" and a message, with related_results when suggestions are available.
 - **include_frontmatter** (boolean, optional, default: False) — For unsliced JSON reads, include opening YAML in content; parsed frontmatter is returned either way. Explicit line ranges are never stripped. CLI: --frontmatter (--include-frontmatter is a deprecated alias).
 - **start_line** (integer | null, optional, default: None) — First document line to read (1-based, inclusive). Defaults to 1 when only end_line is given. Line scans count the full Markdown, including frontmatter, matching cat's default line coordinates.
 - **end_line** (integer | null, optional, default: None) — Last document line to read (inclusive); omitted means EOF. Out-of-file ranges return empty content; invalid/reversed ranges fail. With either bound, text output is numbered and JSON carries coordinates, has_more, and next_start_line/next_end_line. include_frontmatter does not strip an explicitly addressed range. Edits between calls may shift lines.
@@ -102,7 +105,7 @@ bm tool read-note runbook --start-line 120 --end-line 180 --plain
 
 ## EXAMPLES
 
-A miss returns suggestions, not an error (run against the dev project):
+A miss in MCP text mode returns suggestions (run against the dev project):
 
 ```
 read_note("xyzzy definitely missing note", project="dev")

src/basic_memory/mcp/tools/read_note.py

@@ -130,6 +130,8 @@ async def read_note(
             Aliases: limit, per_page.
         output_format: "text" returns markdown content or guidance text.
             "json" returns a structured object with title/permalink/file_path/content/frontmatter.
+            Unresolved notes carry error="NOTE_NOT_FOUND" and a message, with
+            related_results when suggestions are available.
         include_frontmatter: For unsliced JSON reads, include opening YAML in content;
             parsed frontmatter is returned either way. Explicit line ranges are never
             stripped. CLI: --frontmatter (--include-frontmatter is a deprecated alias).
@@ -290,13 +292,15 @@ async def _read_resolved_note(entity_id: str) -> str | dict[str, Any]:
                     "next_end_line": min(total, last + width) if last < total else None,
                 }
 
-            def _empty_json_payload() -> dict[str, Any]:
+            def _not_found_json_payload() -> dict[str, Any]:
                 return {
                     "title": None,
                     "permalink": None,
                     "file_path": None,
                     "content": None,
                     "frontmatter": None,
+                    "error": "NOTE_NOT_FOUND",
+                    "message": f"Note not found: {identifier}",
                 }
 
             def _search_results(payload: object) -> list[dict[str, object]]:
@@ -472,13 +476,13 @@ def _result_external_id(item: dict[str, object]) -> str | None:
             text_candidates = _search_results(text_results)
             if not text_candidates:
                 if output_format == "json":
-                    return _empty_json_payload()
+                    return _not_found_json_payload()
                 return format_not_found_message(active_project.name, identifier)
             # The fallback search is paginated server-side to page_size, so list
             # the whole returned page instead of a hardcoded cap — otherwise the
             # caller's page_size would be silently ignored past the cap.
             if output_format == "json":
-                payload = _empty_json_payload()
+                payload = _not_found_json_payload()
                 payload["related_results"] = [
                     {
                         "title": _result_title(result),

test-int/cli/test_cli_tool_json_failure_integration.py

@@ -6,6 +6,7 @@
 
 import json
 
+import pytest
 from typer.testing import CliRunner
 
 from basic_memory.cli.main import app as cli_app
@@ -14,20 +15,69 @@
 
 
 def test_read_note_not_found(app, app_config, test_project, config_manager):
-    """read-note with non-existent identifier returns JSON with null fields."""
+    """A missing note remains machine-readable but must not report success."""
     result = runner.invoke(
         cli_app,
         ["tool", "read-note", "nonexistent-note-that-does-not-exist"],
     )
 
-    assert result.exit_code == 0
+    assert result.exit_code == 1
     data = json.loads(result.stdout)
-    # MCP tool returns a valid JSON payload with null fields for not-found
+    assert data["error"] == "NOTE_NOT_FOUND"
+    assert data["message"] == "Note not found: nonexistent-note-that-does-not-exist"
+    assert "Note not found" in result.stderr
     assert data["title"] is None
     assert data["permalink"] is None
     assert data["content"] is None
 
 
+@pytest.mark.parametrize("mode", ["piped", "json", "plain", "rich"])
+@pytest.mark.parametrize("related", [False, True])
+def test_read_after_delete_fails_in_every_mode(
+    app, app_config, test_project, config_manager, monkeypatch, mode, related
+):
+    """The actual write/delete/read flow must fail even when search offers alternatives."""
+    monkeypatch.setattr("basic_memory.cli.commands.tool._use_rich", lambda: mode == "rich")
+    title = "Missingneedle"
+    created = runner.invoke(
+        cli_app,
+        ["tool", "write-note", "--title", title, "--folder", "test", "--content", "original"],
+    )
+    assert created.exit_code == 0, created.output
+    deleted = runner.invoke(cli_app, ["tool", "delete-note", title])
+    assert deleted.exit_code == 0, deleted.output
+    if related:
+        alternative = runner.invoke(
+            cli_app,
+            [
+                "tool",
+                "write-note",
+                "--title",
+                "Alternative",
+                "--folder",
+                "test",
+                "--content",
+                f"This mentions {title} but is a different note.",
+            ],
+        )
+        assert alternative.exit_code == 0, alternative.output
+
+    flags = [f"--{mode}"] if mode in {"json", "plain"} else []
+    result = runner.invoke(cli_app, ["tool", "read-note", title, "--frontmatter", *flags])
+    assert result.exit_code == 1, result.output
+    assert f"Note not found: {title}" in result.stderr
+    if mode in {"piped", "json"}:
+        payload = json.loads(result.stdout)
+        assert payload["error"] == "NOTE_NOT_FOUND"
+        assert payload["content"] is None
+        if related:
+            assert payload["related_results"][0]["title"] == "Alternative"
+    else:
+        assert "Note not found" in result.stdout
+        if related:
+            assert "Alternative" in result.stdout
+
+
 def test_write_note_missing_content(app, app_config, test_project, config_manager):
     """write-note without content or stdin returns error exit code."""
     result = runner.invoke(