fix(fetch): surface not-found identifiers in skill fetch script

Mirror the MCP fetch_artifacts fix: format_artifacts no longer silently skips
identifiers with no content. It now lists concrete missing identifiers and
tells the agent to re-check and retry them, with graceful degradation on the
backend `found` flag and a requested-vs-returned backstop. Adds
tests/test_fetch_format.py.

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

Author: rodion-m

skills/codealive-context-engine/SKILL.md

@@ -233,6 +233,11 @@ preview** (up to 3 outgoing/incoming calls per direction). To see the full
 call graph, inheritance, or references, run `relationships.py` with the
 artifact's identifier.
 
+**Missing identifiers.** If an identifier cannot be resolved (or is outside your access
+scope), `fetch.py` does not drop it silently — it prints a "not found" section listing each
+concrete identifier, with a hint to re-check those ids and retry the problematic ones. Tell
+the user which artifacts could not be fetched instead of omitting them.
+
 **Disambiguating an identifier that lives in more than one data source.** Artifact
 identifiers are unique only per data source, so the same identifier can belong to
 more than one data source. If you fetch such an identifier without `--data-source`,

skills/codealive-context-engine/scripts/fetch.py

@@ -102,32 +102,67 @@ def _data_source_miss_hint(data_source: str) -> str:
     )
 
 
-def format_artifacts(data: dict, data_source: str = None) -> str:
-    """Format fetched artifacts for display."""
+def _not_found_lines(not_found: list) -> list:
+    """Lines listing requested identifiers the backend could not resolve or that are
+    outside the caller's access scope, with a re-check/retry hint."""
+    lines = [
+        f"\n{'='*60}",
+        f"⚠️  {len(not_found)} requested identifier(s) not found or inaccessible:",
+    ]
+    for identifier in not_found:
+        lines.append(f"   • {identifier}")
+    lines.append(f"{'='*60}")
+    lines.append(
+        "💡 Do NOT silently omit these. A not-found entry means the identifier did not "
+        "resolve, or points outside the data sources this key can read — it is NOT proof "
+        "the code is absent. Re-check those exact identifiers, re-run search.py or grep.py "
+        "to get fresh ids, then re-fetch the problematic ones; if they still cannot be "
+        "retrieved, tell the user which artifacts could not be fetched."
+    )
+    return lines
+
+
+def format_artifacts(data: dict, data_source: str = None, requested: list = None) -> str:
+    """Format fetched artifacts for display.
+
+    Requested identifiers the backend could not resolve — or that are outside the caller's
+    access scope — come back with ``found: false`` (older backends omit the flag and return
+    ``content: null``). They are NOT dropped silently: each concrete identifier is listed in
+    a "not found" section with a hint to re-check the ids and retry the problematic ones.
+    A ``found: true`` artifact with empty content is still shown (it was located).
+    ``requested`` is the original identifier list; it backstops the diff so an id the
+    backend never echoed back is still surfaced as not-found.
+    """
     artifacts = data.get("artifacts", [])
-    if not artifacts:
-        msg = "No artifacts returned."
-        return msg + _data_source_miss_hint(data_source) if data_source else msg
 
     output = []
     count = 0
     has_any_relationships = False
+    returned_identifiers = set()
+    not_found = []
 
     for artifact in artifacts:
+        identifier = artifact.get("identifier", "unknown")
+        returned_identifiers.add(identifier)
+
         content = artifact.get("content")
-        if content is None:
+        # Prefer the backend's explicit `found` flag; fall back to content-is-null for
+        # older backends that don't emit it yet.
+        found = artifact.get("found")
+        is_missing = (found is False) if found is not None else (content is None)
+        if is_missing:
+            not_found.append(identifier)
             continue
 
         count += 1
-        identifier = artifact.get("identifier", "unknown")
         content_byte_size = artifact.get("contentByteSize")
 
         size_str = f" ({content_byte_size} bytes)" if content_byte_size else ""
         output.append(f"\n{'='*60}")
         output.append(f"📄 {identifier}{size_str}")
         output.append(f"{'='*60}")
         start_line = artifact.get("startLine") or 1
-        output.append(_add_line_numbers(content, start_line))
+        output.append(_add_line_numbers(content or "", start_line))
 
         relationships = artifact.get("relationships")
         if relationships is not None:
@@ -138,11 +173,14 @@ def format_artifacts(data: dict, data_source: str = None) -> str:
                 if _has_any_calls(relationships):
                     has_any_relationships = True
 
-    if not output:
-        msg = "No artifacts found."
-        return msg + _data_source_miss_hint(data_source) if data_source else msg
+    # Backstop: any requested identifier the backend never echoed back is also missing.
+    if requested:
+        for identifier in requested:
+            if identifier not in returned_identifiers and identifier not in not_found:
+                not_found.append(identifier)
 
-    output.append(f"\n({count} artifact(s))")
+    if count > 0:
+        output.append(f"\n({count} artifact(s))")
 
     if has_any_relationships:
         output.append(
@@ -154,6 +192,17 @@ def format_artifacts(data: dict, data_source: str = None) -> str:
             "[--profile callsOnly|inheritanceOnly|allRelevant|referencesOnly]"
         )
 
+    if not_found:
+        output.extend(_not_found_lines(not_found))
+
+    if count == 0:
+        # Nothing was actually fetched. Keep the data-source-specific recovery hint when a
+        # selector was supplied; the not-found section above already lists the ids.
+        if data_source:
+            output.append(_data_source_miss_hint(data_source))
+        if not output:
+            return "No artifacts returned."
+
     return "\n".join(output)
 
 
@@ -200,7 +249,7 @@ def main():
 
         result = client.fetch_artifacts(identifiers=identifiers, data_source=data_source)
 
-        print(format_artifacts(result, data_source=data_source))
+        print(format_artifacts(result, data_source=data_source, requested=identifiers))
 
     except Exception as e:
         print(f"❌ Error: {e}", file=sys.stderr)

tests/test_fetch_format.py

@@ -0,0 +1,83 @@
+"""Unit tests for fetch.py artifact formatting — not-found surfacing.
+
+A requested identifier the backend cannot resolve (or that is outside the caller's scope)
+must never be dropped silently: it has to appear in an explicit "not found" section with the
+concrete identifier and a re-check/retry hint.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+FETCH_PATH = REPO_ROOT / "skills" / "codealive-context-engine" / "scripts" / "fetch.py"
+
+
+def _load_fetch():
+    spec = importlib.util.spec_from_file_location("codealive_fetch", FETCH_PATH)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+fetch = _load_fetch()
+format_artifacts = fetch.format_artifacts
+
+
+def test_found_artifact_is_rendered():
+    data = {"artifacts": [
+        {"identifier": "org/repo::a.py::F", "found": True, "content": "def f():\n    pass", "contentByteSize": 17},
+    ]}
+    out = format_artifacts(data, requested=["org/repo::a.py::F"])
+    assert "org/repo::a.py::F" in out
+    assert "not found or inaccessible" not in out
+
+
+def test_explicit_not_found_is_surfaced_with_concrete_id_and_hint():
+    data = {"artifacts": [
+        {"identifier": "org/repo::a.py::F", "found": True, "content": "x"},
+        {"identifier": "org/repo::missing.py::G", "found": False, "content": None},
+    ]}
+    out = format_artifacts(data, requested=["org/repo::a.py::F", "org/repo::missing.py::G"])
+    assert "1 requested identifier(s) not found" in out
+    assert "org/repo::missing.py::G" in out
+    assert "Do NOT silently omit" in out
+    # the found one is still rendered
+    assert "📄 org/repo::a.py::F" in out
+
+
+def test_legacy_backend_without_found_flag_falls_back_to_null_content():
+    data = {"artifacts": [
+        {"identifier": "org/repo::missing.py::G", "content": None},
+    ]}
+    out = format_artifacts(data, requested=["org/repo::missing.py::G"])
+    assert "not found or inaccessible" in out
+    assert "org/repo::missing.py::G" in out
+
+
+def test_found_but_empty_content_is_rendered_not_missing():
+    data = {"artifacts": [
+        {"identifier": "org/repo::a.py::F", "found": True, "content": ""},
+    ]}
+    out = format_artifacts(data, requested=["org/repo::a.py::F"])
+    assert "📄 org/repo::a.py::F" in out
+    assert "not found or inaccessible" not in out
+
+
+def test_all_found_has_no_not_found_section():
+    data = {"artifacts": [
+        {"identifier": "org/repo::a.py::F", "found": True, "content": "x"},
+    ]}
+    out = format_artifacts(data, requested=["org/repo::a.py::F"])
+    assert "not found or inaccessible" not in out
+
+
+def test_backstop_surfaces_id_backend_never_echoed():
+    data = {"artifacts": [
+        {"identifier": "org/repo::a.py::F", "found": True, "content": "x"},
+    ]}
+    out = format_artifacts(data, requested=["org/repo::a.py::F", "org/repo::ghost.py::Z"])
+    assert "org/repo::ghost.py::Z" in out
+    assert "1 requested identifier(s) not found" in out