@ictechgy/context-guard 0.4.8 → 0.4.10

package/plugins/context-guard/bin/context-guard-artifact

@@ -10,6 +10,8 @@ import json
 import os
 from pathlib import Path
 import re
+import secrets
+import shlex
 import stat
 import sys
 import time
@@ -30,6 +32,17 @@ MAX_COMMAND_PREVIEW_BYTES = 2_048
 MAX_TOP_ERROR_RECEIPTS = 12
 MAX_DUPLICATE_GROUPS = 12
 MAX_SUGGESTED_QUERIES = 12
+SEARCH_SCHEMA_VERSION = "contextguard.artifact.search.v1"
+DEFAULT_SEARCH_MAX_ARTIFACTS = 100
+MAX_SEARCH_MAX_ARTIFACTS = 1_000
+DEFAULT_SEARCH_MAX_MATCHES = 40
+MAX_SEARCH_MAX_MATCHES = 1_000
+DEFAULT_SEARCH_CONTEXT_LINES = 1
+MAX_SEARCH_CONTEXT_LINES = 20
+DEFAULT_SEARCH_SNIPPET_CHARS = 360
+MAX_SEARCH_SNIPPET_CHARS = 2_000
+MAX_SEARCH_PATTERN_BYTES = 512
+SEARCH_TRUNCATED_COUNT_UNKNOWN = "lower_bound"
 ARTIFACT_ID_RE = re.compile(r"^[a-f0-9]{16,64}$")
 ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
     "tmp": Path("/private/tmp"),
@@ -183,15 +196,50 @@ def sanitize_one_line(text: str, *, show_paths: bool = False) -> str:
     return cap_utf8_bytes(cap_line(" ".join(sanitized.strip().split())), MAX_COMMAND_PREVIEW_BYTES)
 
 
+NO_FOLLOW_SUPPORTED = hasattr(os, "O_NOFOLLOW")
+DIR_FD_OPEN_SUPPORTED = bool(os.supports_dir_fd and os.open in os.supports_dir_fd)
+DIR_FD_MKDIR_SUPPORTED = bool(os.supports_dir_fd and os.mkdir in os.supports_dir_fd)
+DIR_FD_STAT_SUPPORTED = bool(os.supports_dir_fd and os.stat in os.supports_dir_fd)
+DIR_FD_UNLINK_SUPPORTED = bool(os.supports_dir_fd and os.unlink in os.supports_dir_fd)
+
+
+def dir_fd_replace_supported() -> bool:
+    # Some Python builds support src_dir_fd/dst_dir_fd for os.replace without
+    # listing os.replace in os.supports_dir_fd, so use a signature/probe-light
+    # check instead of os.supports_dir_fd membership.
+    try:
+        import inspect
+
+        signature = inspect.signature(os.replace)
+    except (TypeError, ValueError):
+        return True
+    return "src_dir_fd" in signature.parameters and "dst_dir_fd" in signature.parameters
+
+
+DIR_FD_REPLACE_SUPPORTED = dir_fd_replace_supported()
+
+
+def os_error_detail(exc: OSError) -> str:
+    detail = exc.strerror or str(exc) or exc.__class__.__name__
+    if exc.errno is not None:
+        return f"{detail} (errno {exc.errno})"
+    return detail
+
+
+def reject_parent_traversal(path: Path, *, label: str) -> None:
+    if any(part == ".." for part in path.expanduser().parts):
+        raise ValueError(f"{label} must not contain parent traversal")
+
+
 def ensure_private_dir(path: Path) -> None:
-    path = normalize_allowed_first_absolute_symlink(path)
-    reject_symlink_components(path)
-    path.mkdir(parents=True, exist_ok=True)
-    reject_symlink_components(path)
+    fd = open_private_directory_no_follow(path, label="artifact directory", create=True)
     try:
-        os.chmod(path, 0o700)
-    except OSError:
-        pass
+        try:
+            os.fchmod(fd, 0o700)
+        except OSError:
+            pass
+    finally:
+        os.close(fd)
 
 
 def reject_symlink_components(path: Path) -> None:
@@ -243,33 +291,156 @@ def read_bounded_private_text(path: Path, max_bytes: int) -> str:
         os.close(fd)
 
 
-def write_private_text(path: Path, text: str) -> None:
-    path = normalize_allowed_first_absolute_symlink(path)
-    ensure_private_dir(path.parent)
-    tmp = path.with_name(path.name + f".tmp-{os.getpid()}-{time.time_ns()}")
-    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
-    fd = os.open(str(tmp), flags, 0o600)
+def no_follow_dir_flags() -> int:
+    if not NO_FOLLOW_SUPPORTED:
+        raise RuntimeError("artifact writes require O_NOFOLLOW support")
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    return flags
+
+
+def temp_file_flags() -> int:
+    if not NO_FOLLOW_SUPPORTED:
+        raise RuntimeError("artifact writes require O_NOFOLLOW support")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NOCTTY"):
+        flags |= os.O_NOCTTY
+    return flags
+
+
+def open_private_directory_no_follow(path: Path, *, label: str, create: bool) -> int:
+    reject_parent_traversal(path, label=label)
+    path = normalize_allowed_first_absolute_symlink(path.expanduser())
+    if not DIR_FD_OPEN_SUPPORTED:
+        raise RuntimeError(f"{label} requires dir_fd open support")
+    if create and not DIR_FD_MKDIR_SUPPORTED:
+        raise RuntimeError(f"{label} requires dir_fd mkdir support")
+    flags = no_follow_dir_flags()
+    if path.is_absolute():
+        current_fd = os.open(path.anchor or os.sep, os.O_RDONLY | (os.O_CLOEXEC if hasattr(os, "O_CLOEXEC") else 0))
+        parts = path.parts[1:]
+    else:
+        current_fd = os.open(".", flags)
+        parts = path.parts
     try:
-        with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
-            handle.write(text)
-    except Exception:
-        try:
-            tmp.unlink()
-        except FileNotFoundError:
-            pass
-        raise
+        for part in parts:
+            if part in {"", "."}:
+                continue
+            if part == "..":
+                raise RuntimeError(f"{label} must not contain parent traversal")
+            try:
+                next_fd = os.open(part, flags, dir_fd=current_fd)
+            except FileNotFoundError:
+                if not create:
+                    raise
+                os.mkdir(part, 0o700, dir_fd=current_fd)
+                next_fd = os.open(part, flags, dir_fd=current_fd)
+            try:
+                if not stat.S_ISDIR(os.fstat(next_fd).st_mode):
+                    raise RuntimeError(f"{label} must not traverse non-directory components")
+            except Exception:
+                os.close(next_fd)
+                raise
+            os.close(current_fd)
+            current_fd = next_fd
+        owned_fd = current_fd
+        current_fd = -1
+        return owned_fd
+    except OSError as exc:
+        raise RuntimeError(f"could not inspect {label}: {os_error_detail(exc)}") from exc
+    finally:
+        if current_fd >= 0:
+            os.close(current_fd)
+
+
+def precheck_artifact_leaf(parent_fd: int, leaf: str, *, label: str) -> None:
+    if not DIR_FD_STAT_SUPPORTED:
+        raise RuntimeError(f"{label} requires dir_fd stat support")
     try:
-        os.replace(tmp, path)
-    except Exception:
-        try:
-            tmp.unlink()
-        except FileNotFoundError:
-            pass
-        raise
+        st = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        raise RuntimeError(f"could not inspect {label}: {os_error_detail(exc)}") from exc
+    if not stat.S_ISREG(st.st_mode):
+        raise RuntimeError(f"{label} must be missing or a regular file")
+
+
+def write_all_fd(fd: int, data: bytes) -> None:
+    view = memoryview(data)
+    offset = 0
+    while offset < len(view):
+        written = os.write(fd, view[offset:])
+        if written <= 0:
+            raise OSError("short write")
+        offset += written
+
+
+def fsync_required(fd: int, *, label: str, committed: bool = False) -> None:
     try:
-        os.chmod(path, 0o600)
+        os.fsync(fd)
+    except OSError as exc:
+        if committed:
+            raise RuntimeError(f"committed_but_parent_fsync_failed: {os_error_detail(exc)}") from exc
+        raise RuntimeError(f"could not fsync {label}: {os_error_detail(exc)}") from exc
+
+
+def write_private_text(path: Path, text: str) -> None:
+    reject_parent_traversal(path, label="artifact file")
+    path = normalize_allowed_first_absolute_symlink(path.expanduser())
+    if not DIR_FD_REPLACE_SUPPORTED:
+        raise RuntimeError("artifact writes require dir_fd replace support")
+    if not DIR_FD_UNLINK_SUPPORTED:
+        raise RuntimeError("artifact writes require dir_fd unlink support")
+    parent_fd = open_private_directory_no_follow(path.parent, label="artifact directory", create=True)
+    try:
+        os.fchmod(parent_fd, 0o700)
     except OSError:
         pass
+    fd = -1
+    temp_leaf: str | None = None
+    try:
+        leaf = path.name
+        if leaf in {"", ".", ".."}:
+            raise RuntimeError("artifact file must name a regular file")
+        precheck_artifact_leaf(parent_fd, leaf, label="artifact file")
+        for _attempt in range(20):
+            candidate = f".{leaf}.{os.getpid()}.{secrets.token_hex(8)}.tmp"
+            try:
+                fd = os.open(candidate, temp_file_flags(), 0o600, dir_fd=parent_fd)
+                temp_leaf = candidate
+                break
+            except FileExistsError:
+                continue
+        if fd < 0 or temp_leaf is None:
+            raise RuntimeError("could not create temporary artifact file")
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise RuntimeError("temporary artifact file must be a regular file")
+        os.fchmod(fd, 0o600)
+        write_all_fd(fd, text.encode("utf-8"))
+        fsync_required(fd, label="artifact temp file")
+        os.close(fd)
+        fd = -1
+        fsync_required(parent_fd, label="artifact directory before replace")
+        os.replace(temp_leaf, leaf, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
+        temp_leaf = None
+        fsync_required(parent_fd, label="artifact directory after replace", committed=True)
+    except OSError as exc:
+        raise RuntimeError(f"could not write artifact file: {os_error_detail(exc)}") from exc
+    finally:
+        if fd >= 0:
+            os.close(fd)
+        if temp_leaf is not None:
+            try:
+                os.unlink(temp_leaf, dir_fd=parent_fd)
+            except OSError:
+                pass
+        os.close(parent_fd)
 
 
 def read_bounded_stdin(max_bytes: int) -> tuple[str, bool, int]:
@@ -283,6 +454,7 @@ def read_bounded_stdin(max_bytes: int) -> tuple[str, bool, int]:
 def artifact_paths(directory: Path, artifact_id: str) -> tuple[Path, Path]:
     if not ARTIFACT_ID_RE.fullmatch(artifact_id):
         raise ValueError("artifact id must be 16-64 lowercase hex chars")
+    reject_parent_traversal(directory, label="artifact directory")
     directory = normalize_allowed_first_absolute_symlink(directory)
     return directory / f"{artifact_id}.txt", directory / f"{artifact_id}.json"
 
@@ -295,15 +467,21 @@ def artifact_read_directories(raw_dir: str) -> list[Path]:
     default. Reads and listings include that legacy default so old receipts keep
     working; stores intentionally continue to use only the new path.
     """
-    primary = normalize_allowed_first_absolute_symlink(Path(raw_dir).expanduser())
+    raw_path = Path(raw_dir).expanduser()
+    reject_parent_traversal(raw_path, label="artifact directory")
+    primary = normalize_allowed_first_absolute_symlink(raw_path)
     directories = [primary]
-    if Path(raw_dir).expanduser() == Path(DEFAULT_ARTIFACT_DIR):
+    if default_artifact_dir_requested(raw_dir):
         legacy = normalize_allowed_first_absolute_symlink(Path(LEGACY_ARTIFACT_DIR).expanduser())
         if legacy != primary:
             directories.append(legacy)
     return directories
 
 
+def default_artifact_dir_requested(raw_dir: str) -> bool:
+    return Path(raw_dir).expanduser() == Path(DEFAULT_ARTIFACT_DIR)
+
+
 CONTENT_TYPE_VALUES = ("json", "diff", "log", "search", "code", "prose", "text")
 # Recommended retrieval strategy per content type. Pattern-oriented payloads
 # (logs, search hits, diffs) are best sliced by `--pattern`; structured or
@@ -449,8 +627,27 @@ def build_retrieval_hints(
     return hints
 
 
-def line_query_cli(artifact_id: str, start: int, end: int) -> str:
-    cli = f"context-guard-artifact get {artifact_id} --lines {start}:{end}"
+def artifact_dir_cli_prefix(raw_dir: str | None, *, show_paths: bool = False) -> str:
+    if not raw_dir or default_artifact_dir_requested(raw_dir):
+        return "context-guard-artifact"
+    if not show_paths:
+        return "context-guard-artifact --dir <artifact_dir>"
+    return f"context-guard-artifact --dir {shlex.quote(raw_dir)}"
+
+
+def artifact_dir_cli_is_exact(raw_dir: str | None, *, show_paths: bool = False) -> bool:
+    return not raw_dir or default_artifact_dir_requested(raw_dir) or show_paths
+
+
+def line_query_cli(
+    artifact_id: str,
+    start: int,
+    end: int,
+    *,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> str:
+    cli = f"{artifact_dir_cli_prefix(raw_dir, show_paths=show_paths)} get {artifact_id} --lines {start}:{end}"
     requested_lines = end - start + 1
     if requested_lines > DEFAULT_MAX_LINES:
         cli += f" --max-lines {min(requested_lines, MAX_QUERY_LINES)}"
@@ -745,6 +942,26 @@ def load_metadata(directory: Path, artifact_id: str) -> dict[str, object]:
     return data
 
 
+def load_verified_artifact(directory: Path, artifact_id: str) -> tuple[dict[str, object], Path, str]:
+    metadata = load_metadata(directory, artifact_id)
+    content_path, _meta_path = artifact_paths(directory, artifact_id)
+    stored_output = metadata.get("stored_output")
+    expected_sha = stored_output.get("sha256") if isinstance(stored_output, dict) else None
+    if not isinstance(expected_sha, str) or not re.fullmatch(r"[a-f0-9]{64}", expected_sha):
+        raise ValueError(f"artifact metadata missing stored_output sha256: {artifact_id}")
+    expected_bytes = stored_output.get("bytes") if isinstance(stored_output, dict) else None
+    if not isinstance(expected_bytes, int) or expected_bytes < 0 or expected_bytes > MAX_MAX_BYTES:
+        raise ValueError(f"artifact metadata has invalid stored_output bytes: {artifact_id}")
+    actual_size = regular_private_file_size(content_path)
+    if actual_size != expected_bytes:
+        raise ValueError(f"artifact content checksum mismatch: {artifact_id}")
+    content = read_bounded_private_text(content_path, expected_bytes)
+    actual_sha = hashlib.sha256(content.encode("utf-8", errors="replace")).hexdigest()
+    if actual_sha != expected_sha:
+        raise ValueError(f"artifact content checksum mismatch: {artifact_id}")
+    return metadata, content_path, content
+
+
 def parse_line_range(value: str | None) -> tuple[int, int] | None:
     if not value:
         return None
@@ -766,6 +983,149 @@ def cap_text(text: str, max_chars: int) -> tuple[str, bool]:
     return text[:keep].rstrip() + marker, True
 
 
+def search_literal(value: str) -> str:
+    if not value:
+        raise ValueError("search pattern must not be empty")
+    if "\x00" in value:
+        raise ValueError("search pattern must not contain NUL bytes")
+    size = len(value.encode("utf-8", errors="replace"))
+    if size > MAX_SEARCH_PATTERN_BYTES:
+        raise ValueError(f"search pattern exceeds {MAX_SEARCH_PATTERN_BYTES} bytes")
+    return value
+
+
+def safe_query_label(value: str) -> str:
+    return sanitize_one_line(value, show_paths=False)
+
+
+def artifact_dir_label(raw_dir: str) -> str:
+    if default_artifact_dir_requested(raw_dir):
+        return "default"
+    return sanitize_one_line(raw_dir, show_paths=False)
+
+
+def metadata_text_field(metadata: dict[str, object], key: str) -> str | None:
+    value = metadata.get(key)
+    if not isinstance(value, str):
+        return None
+    return sanitize_one_line(value, show_paths=False)
+
+
+def metadata_content_type(metadata: dict[str, object]) -> str:
+    value = metadata.get("content_type")
+    return value if isinstance(value, str) and value in CONTENT_TYPE_VALUES else "text"
+
+
+def metadata_candidate_paths(directory: Path, limit: int) -> tuple[list[Path], int, int]:
+    candidates: list[Path] = []
+    skipped = 0
+    truncated_lower_bound = 0
+    if limit <= 0:
+        return candidates, skipped, 0
+    try:
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                name = entry.name
+                if not name.endswith(".json"):
+                    continue
+                if not ARTIFACT_ID_RE.fullmatch(name[:-5]):
+                    skipped += 1
+                    continue
+                try:
+                    if not entry.is_file(follow_symlinks=False):
+                        skipped += 1
+                        continue
+                except OSError:
+                    skipped += 1
+                    continue
+                if len(candidates) >= limit:
+                    truncated_lower_bound += 1
+                    break
+                candidates.append(directory / name)
+    except OSError:
+        return candidates, skipped + 1, truncated_lower_bound
+    return sorted(candidates), skipped, truncated_lower_bound
+
+
+def search_match_record(
+    *,
+    artifact_id: str,
+    line_number: int,
+    lines: list[str],
+    context_lines: int,
+    snippet_chars: int,
+    metadata: dict[str, object],
+    raw_dir: str,
+    show_paths: bool,
+) -> dict[str, object]:
+    start = max(1, line_number - context_lines)
+    end = min(len(lines), line_number + context_lines)
+    cli_exact = artifact_dir_cli_is_exact(raw_dir, show_paths=show_paths)
+
+    def line_item(number: int) -> dict[str, object]:
+        return {"line": number, "text": cap_line(lines[number - 1].rstrip("\n"), limit=snippet_chars)}
+
+    return {
+        "artifact_id": artifact_id,
+        "line": line_number,
+        "text": cap_line(lines[line_number - 1].rstrip("\n"), limit=snippet_chars),
+        "context_before": [line_item(number) for number in range(start, line_number)],
+        "context_after": [line_item(number) for number in range(line_number + 1, end + 1)],
+        "content_type": metadata_content_type(metadata),
+        "command_preview": metadata_text_field(metadata, "command_preview"),
+        "retrieval": {
+            "selector": {"type": "lines", "start": start, "end": end},
+            "cli": line_query_cli(artifact_id, start, end, raw_dir=raw_dir, show_paths=show_paths),
+            "exact": cli_exact,
+            "dir_argument": "default" if default_artifact_dir_requested(raw_dir) else ("included" if show_paths else "redacted"),
+            "note": (
+                None
+                if cli_exact
+                else "custom artifact directory is redacted; rerun with the same --dir used for search, or pass search --show-paths to emit a directly executable local CLI"
+            ),
+        },
+    }
+
+
+def search_artifact_content(
+    *,
+    artifact_id: str,
+    metadata: dict[str, object],
+    content: str,
+    literal: str,
+    ignore_case: bool,
+    context_lines: int,
+    snippet_chars: int,
+    remaining_matches: int,
+    raw_dir: str,
+    show_paths: bool,
+) -> tuple[list[dict[str, object]], int]:
+    lines = content.splitlines()
+    needle = literal.casefold() if ignore_case else literal
+    matches: list[dict[str, object]] = []
+    matched_lines = 0
+    for line_number, line in enumerate(lines, start=1):
+        haystack = line.casefold() if ignore_case else line
+        if needle not in haystack:
+            continue
+        matched_lines += 1
+        if len(matches) >= remaining_matches:
+            continue
+        matches.append(
+            search_match_record(
+                artifact_id=artifact_id,
+                line_number=line_number,
+                lines=lines,
+                context_lines=context_lines,
+                snippet_chars=snippet_chars,
+                metadata=metadata,
+                raw_dir=raw_dir,
+                show_paths=show_paths,
+            )
+        )
+    return matches, matched_lines
+
+
 def query_content(
     content: str,
     *,
@@ -805,8 +1165,7 @@ def get_command(args: argparse.Namespace) -> int:
         last_missing: FileNotFoundError | None = None
         for directory in artifact_read_directories(args.dir):
             try:
-                metadata = load_metadata(directory, artifact_id)
-                content_path, _meta_path = artifact_paths(directory, artifact_id)
+                metadata, _content_path, content = load_verified_artifact(directory, artifact_id)
                 break
             except FileNotFoundError as exc:
                 last_missing = exc
@@ -815,19 +1174,9 @@ def get_command(args: argparse.Namespace) -> int:
                 raise last_missing
             raise FileNotFoundError(f"artifact not found: {artifact_id}")
         stored_output = metadata.get("stored_output")
-        expected_sha = stored_output.get("sha256") if isinstance(stored_output, dict) else None
-        if not isinstance(expected_sha, str) or not re.fullmatch(r"[a-f0-9]{64}", expected_sha):
-            raise ValueError(f"artifact metadata missing stored_output sha256: {artifact_id}")
         expected_bytes = stored_output.get("bytes") if isinstance(stored_output, dict) else None
-        if not isinstance(expected_bytes, int) or expected_bytes < 0 or expected_bytes > MAX_MAX_BYTES:
+        if not isinstance(expected_bytes, int):
             raise ValueError(f"artifact metadata has invalid stored_output bytes: {artifact_id}")
-        actual_size = regular_private_file_size(content_path)
-        if actual_size != expected_bytes:
-            raise ValueError(f"artifact content checksum mismatch: {artifact_id}")
-        content = read_bounded_private_text(content_path, expected_bytes)
-        actual_sha = hashlib.sha256(content.encode("utf-8", errors="replace")).hexdigest()
-        if actual_sha != expected_sha:
-            raise ValueError(f"artifact content checksum mismatch: {artifact_id}")
         default_max_chars = max(DEFAULT_MAX_CHARS, expected_bytes) if full else DEFAULT_MAX_CHARS
         max_chars = bounded_int(args.max_chars, default_max_chars, 1, MAX_MAX_BYTES)
         line_range = parse_line_range(args.lines)
@@ -856,6 +1205,138 @@ def get_command(args: argparse.Namespace) -> int:
     return 0
 
 
+def search_command(args: argparse.Namespace) -> int:
+    try:
+        literal = search_literal(args.pattern)
+        max_artifacts = bounded_int(args.max_artifacts, DEFAULT_SEARCH_MAX_ARTIFACTS, 1, MAX_SEARCH_MAX_ARTIFACTS)
+        max_matches = bounded_int(args.max_matches, DEFAULT_SEARCH_MAX_MATCHES, 1, MAX_SEARCH_MAX_MATCHES)
+        context_lines = bounded_int(args.context_lines, DEFAULT_SEARCH_CONTEXT_LINES, 0, MAX_SEARCH_CONTEXT_LINES)
+        snippet_chars = bounded_int(args.max_snippet_chars, DEFAULT_SEARCH_SNIPPET_CHARS, 1, MAX_SEARCH_SNIPPET_CHARS)
+        ignore_case = bool(args.ignore_case)
+        matches: list[dict[str, object]] = []
+        seen: set[str] = set()
+        scanned_artifacts = 0
+        skipped_artifacts = 0
+        total_matched_lines = 0
+        meta_candidates_seen = 0
+        scan_truncated = False
+        scan_truncated_count = 0
+        matched_artifact_ids: set[str] = set()
+
+        for directory in artifact_read_directories(args.dir):
+            remaining_candidates = max_artifacts - meta_candidates_seen
+            if remaining_candidates <= 0:
+                scan_truncated = True
+                break
+            try:
+                reject_symlink_components(directory)
+                directory_is_safe = directory.is_dir() and not directory.is_symlink()
+            except RuntimeError:
+                directory_is_safe = False
+            if not directory_is_safe:
+                continue
+            meta_paths, skipped_candidates, truncated_candidates = metadata_candidate_paths(directory, remaining_candidates)
+            skipped_artifacts += skipped_candidates
+            if truncated_candidates:
+                scan_truncated = True
+                scan_truncated_count += truncated_candidates
+            for meta_path in meta_paths:
+                meta_candidates_seen += 1
+                try:
+                    data = json.loads(read_bounded_private_text(meta_path, MAX_METADATA_BYTES))
+                except (OSError, ValueError, RuntimeError, json.JSONDecodeError):
+                    skipped_artifacts += 1
+                    continue
+                artifact_id = str(data.get("artifact_id", "")) if isinstance(data, dict) else ""
+                if not (isinstance(data, dict) and ARTIFACT_ID_RE.fullmatch(artifact_id)) or artifact_id in seen:
+                    skipped_artifacts += 1
+                    continue
+                seen.add(artifact_id)
+                if scanned_artifacts >= max_artifacts:
+                    scan_truncated = True
+                    scan_truncated_count += 1
+                    continue
+                try:
+                    metadata, _content_path, content = load_verified_artifact(directory, artifact_id)
+                except (OSError, ValueError, RuntimeError, json.JSONDecodeError):
+                    skipped_artifacts += 1
+                    continue
+                scanned_artifacts += 1
+                remaining = max(0, max_matches - len(matches))
+                artifact_matches, artifact_match_count = search_artifact_content(
+                    artifact_id=artifact_id,
+                    metadata=metadata,
+                    content=content,
+                    literal=literal,
+                    ignore_case=ignore_case,
+                    context_lines=context_lines,
+                    snippet_chars=snippet_chars,
+                    remaining_matches=remaining,
+                    raw_dir=args.dir,
+                    show_paths=bool(getattr(args, "show_paths", False)),
+                )
+                if artifact_match_count:
+                    matched_artifact_ids.add(artifact_id)
+                total_matched_lines += artifact_match_count
+                matches.extend(artifact_matches)
+        payload = {
+            "tool": "context-guard-artifact",
+            "schema_version": SEARCH_SCHEMA_VERSION,
+            "mode": "search",
+            "query": {
+                "label": safe_query_label(literal),
+                "raw_pattern_stored": False,
+                "literal": True,
+                "ignore_case": ignore_case,
+            },
+            "artifact_dir": artifact_dir_label(args.dir),
+            "scanned_artifacts": scanned_artifacts,
+            "skipped_artifacts": skipped_artifacts,
+            "matched_artifacts": len(matched_artifact_ids),
+            "matched_lines": total_matched_lines,
+            "metadata_candidates_scanned": meta_candidates_seen,
+            "matches": matches,
+            "matches_truncated_count": max(0, total_matched_lines - max_matches),
+            "artifact_scan_truncated": scan_truncated,
+            "artifact_scan_truncated_count": scan_truncated_count,
+            "artifact_scan_truncated_count_mode": SEARCH_TRUNCATED_COUNT_UNKNOWN if scan_truncated else "exact",
+            "limits": {
+                "max_artifacts": max_artifacts,
+                "max_matches": max_matches,
+                "context_lines": context_lines,
+                "max_snippet_chars": snippet_chars,
+            },
+            "sandbox": {
+                "local_only": True,
+                "workflow": ["store", "search", "get"],
+                "exact_rehydration": "use matches[].retrieval.cli when exact=true; for redacted custom dirs, reuse the same --dir or opt into --show-paths",
+            },
+            "claim_boundary": {
+                "local_only": True,
+                "stored_content_is_sanitized_copy": True,
+                "hosted_api_token_or_cost_savings_claim_allowed": False,
+                "exact_rehydration_required_before_relying_on_omitted_detail": True,
+            },
+        }
+    except (FileNotFoundError, ValueError, OSError, json.JSONDecodeError) as exc:
+        print(f"context-guard-artifact: {exc}", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+    else:
+        for item in payload["matches"]:
+            if isinstance(item, dict):
+                print(f"{item.get('artifact_id')}:{item.get('line')}: {item.get('text')}")
+                retrieval = item.get("retrieval")
+                if isinstance(retrieval, dict):
+                    print(f"  rehydrate={retrieval.get('cli')}")
+        if not payload["matches"]:
+            print("no matches")
+        elif payload["matches_truncated_count"]:
+            print(f"matches_truncated_count={payload['matches_truncated_count']}")
+    return 0
+
+
 def list_command(args: argparse.Namespace) -> int:
     items: list[dict[str, object]] = []
     seen: set[str] = set()
@@ -918,6 +1399,21 @@ def build_parser() -> argparse.ArgumentParser:
     list_parser = subparsers.add_parser("list", help="list stored artifacts")
     list_parser.add_argument("--json", action="store_true", help="emit list JSON")
     list_parser.set_defaults(func=list_command)
+
+    search = subparsers.add_parser("search", help="search stored sanitized artifacts by literal text")
+    search.add_argument("pattern", help=f"literal substring to search for (max {MAX_SEARCH_PATTERN_BYTES} UTF-8 bytes)")
+    search.add_argument("--ignore-case", action="store_true", help="case-insensitive literal search")
+    search.add_argument("--context-lines", type=int, default=DEFAULT_SEARCH_CONTEXT_LINES, help=f"context lines around each match (default: {DEFAULT_SEARCH_CONTEXT_LINES})")
+    search.add_argument("--max-artifacts", type=int, default=DEFAULT_SEARCH_MAX_ARTIFACTS, help=f"maximum artifacts to scan (default: {DEFAULT_SEARCH_MAX_ARTIFACTS})")
+    search.add_argument("--max-matches", type=int, default=DEFAULT_SEARCH_MAX_MATCHES, help=f"maximum match records to return (default: {DEFAULT_SEARCH_MAX_MATCHES})")
+    search.add_argument("--max-snippet-chars", type=int, default=DEFAULT_SEARCH_SNIPPET_CHARS, help=f"maximum characters per displayed line (default: {DEFAULT_SEARCH_SNIPPET_CHARS})")
+    search.add_argument(
+        "--show-paths",
+        action="store_true",
+        help="show raw custom --dir values in rehydration commands; local debugging only because private paths may be exposed",
+    )
+    search.add_argument("--json", action="store_true", help="emit sandbox search JSON")
+    search.set_defaults(func=search_command)
     return parser