@ictechgy/context-guard 0.4.9 → 0.4.11

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,18 @@ 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"
+OUTPUT_SANDBOX_SCHEMA_VERSION = "contextguard.artifact.output-sandbox.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 +197,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:
@@ -213,22 +262,38 @@ def reject_symlink_components(path: Path) -> None:
 
 def regular_private_file_size(path: Path) -> int:
     path = normalize_allowed_first_absolute_symlink(path)
-    reject_symlink_components(path.parent)
-    st = os.lstat(path)
-    if stat.S_ISLNK(st.st_mode):
-        raise ValueError(f"artifact file must not be a symlink: {path.name}")
-    if not stat.S_ISREG(st.st_mode):
-        raise ValueError(f"artifact file must be a regular file: {path.name}")
-    return int(st.st_size)
+    parent_fd = open_private_directory_no_follow(path.parent, label="artifact directory", create=False)
+    try:
+        leaf = path.name
+        if leaf in {"", ".", ".."}:
+            raise ValueError("artifact file must name a regular file")
+        if not DIR_FD_STAT_SUPPORTED:
+            raise RuntimeError("artifact reads require dir_fd stat support")
+        st = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+        if stat.S_ISLNK(st.st_mode):
+            raise ValueError(f"artifact file must not be a symlink: {path.name}")
+        if not stat.S_ISREG(st.st_mode):
+            raise ValueError(f"artifact file must be a regular file: {path.name}")
+        return int(st.st_size)
+    finally:
+        os.close(parent_fd)
 
 
 def read_bounded_private_text(path: Path, max_bytes: int) -> str:
     path = normalize_allowed_first_absolute_symlink(path)
-    size = regular_private_file_size(path)
-    if size > max_bytes:
-        raise ValueError(f"artifact file exceeds trusted size cap: {path.name}: {size} > {max_bytes}")
-    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
-    fd = os.open(str(path), flags)
+    parent_fd = open_private_directory_no_follow(path.parent, label="artifact directory", create=False)
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    leaf = path.name
+    if leaf in {"", ".", ".."}:
+        os.close(parent_fd)
+        raise ValueError("artifact file must name a regular file")
+    try:
+        fd = os.open(leaf, flags, dir_fd=parent_fd)
+    except OSError:
+        os.close(parent_fd)
+        raise
     try:
         st = os.fstat(fd)
         if not stat.S_ISREG(st.st_mode):
@@ -241,35 +306,161 @@ def read_bounded_private_text(path: Path, max_bytes: int) -> str:
         return data.decode("utf-8", errors="replace")
     finally:
         os.close(fd)
+        os.close(parent_fd)
+
+
+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:
+        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 FileNotFoundError:
+        raise
+    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 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 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:
-        with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
-            handle.write(text)
-    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.replace(tmp, path)
-    except Exception:
-        try:
-            tmp.unlink()
-        except FileNotFoundError:
-            pass
-        raise
+        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.chmod(path, 0o600)
+        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 +474,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 +487,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
@@ -396,6 +594,8 @@ def build_retrieval_hints(
     content_type: str,
     strategy: str,
     total_lines: int,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
 ) -> list[dict[str, object]]:
     """Build deterministic, machine-readable retrieval hints for bounded round-trip.
 
@@ -413,8 +613,8 @@ def build_retrieval_hints(
         lines_hint: dict[str, object] = {
             "type": "lines",
             "selector": {"start": 1, "end": end_line},
-            "cli": line_query_cli(artifact_id, 1, end_line),
-            "exact": total_lines <= MAX_QUERY_LINES,
+            "cli": line_query_cli(artifact_id, 1, end_line, raw_dir=raw_dir, show_paths=show_paths),
+            "exact": total_lines <= MAX_QUERY_LINES and artifact_dir_cli_is_exact(raw_dir, show_paths=show_paths),
         }
         if end_line > DEFAULT_MAX_LINES:
             lines_hint["max_lines"] = end_line
@@ -436,37 +636,69 @@ def build_retrieval_hints(
             {
                 "type": "pattern",
                 "selector": {"pattern": anchor},
-                "cli": f"context-guard-artifact get {artifact_id} --pattern '{anchor}'",
+                "cli": f"{artifact_dir_cli_prefix(raw_dir, show_paths=show_paths)} get {artifact_id} --pattern {shlex.quote(anchor)}",
             }
         )
     hints.append(
         {
             "type": "head",
             "selector": {"max_lines": DEFAULT_MAX_LINES},
-            "cli": f"context-guard-artifact get {artifact_id} --max-lines {DEFAULT_MAX_LINES}",
+            "cli": f"{artifact_dir_cli_prefix(raw_dir, show_paths=show_paths)} get {artifact_id} --max-lines {DEFAULT_MAX_LINES}",
         }
     )
     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)}"
     return cli
 
 
-def line_receipt(artifact_id: str, line_number: int, text: str) -> dict[str, object]:
+def line_receipt(
+    artifact_id: str,
+    line_number: int,
+    text: str,
+    *,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> dict[str, object]:
     return {
         "line": line_number,
         "text": cap_digest_text(text.strip()),
         "selector": {"type": "lines", "start": line_number, "end": line_number},
-        "cli": line_query_cli(artifact_id, line_number, line_number),
+        "cli": line_query_cli(artifact_id, line_number, line_number, raw_dir=raw_dir, show_paths=show_paths),
     }
 
 
-def build_top_error_receipts(artifact_id: str, lines: list[str]) -> list[dict[str, object]]:
+def build_top_error_receipts(
+    artifact_id: str,
+    lines: list[str],
+    *,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> list[dict[str, object]]:
     receipts: list[dict[str, object]] = []
     seen: set[str] = set()
     for line_number, line in enumerate(lines, start=1):
@@ -475,7 +707,7 @@ def build_top_error_receipts(artifact_id: str, lines: list[str]) -> list[dict[st
         text = cap_digest_text(line.strip())
         if not text or text in seen:
             continue
-        receipt = line_receipt(artifact_id, line_number, text)
+        receipt = line_receipt(artifact_id, line_number, text, raw_dir=raw_dir, show_paths=show_paths)
         receipts.append(receipt)
         seen.add(text)
         if len(receipts) >= MAX_TOP_ERROR_RECEIPTS:
@@ -483,7 +715,14 @@ def build_top_error_receipts(artifact_id: str, lines: list[str]) -> list[dict[st
     return receipts
 
 
-def build_duplicate_line_groups(artifact_id: str, lines: list[str], *, limit: int = MAX_DUPLICATE_GROUPS) -> list[dict[str, object]]:
+def build_duplicate_line_groups(
+    artifact_id: str,
+    lines: list[str],
+    *,
+    limit: int = MAX_DUPLICATE_GROUPS,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> list[dict[str, object]]:
     counts: dict[str, int] = {}
     first_line: dict[str, int] = {}
     for line_number, line in enumerate(lines, start=1):
@@ -506,13 +745,20 @@ def build_duplicate_line_groups(artifact_id: str, lines: list[str], *, limit: in
                 "first_line": line_number,
                 "text": text,
                 "selector": {"type": "lines", "start": line_number, "end": line_number},
-                "cli": line_query_cli(artifact_id, line_number, line_number),
+                "cli": line_query_cli(artifact_id, line_number, line_number, raw_dir=raw_dir, show_paths=show_paths),
             }
         )
     return groups
 
 
-def build_digest(sanitized_text: str, *, artifact_id: str, redacted_lines: int) -> dict[str, object]:
+def build_digest(
+    sanitized_text: str,
+    *,
+    artifact_id: str,
+    redacted_lines: int,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> dict[str, object]:
     lines = sanitized_text.splitlines()
     top_errors = compact_items(
         (line for line in lines if ERROR_RE.search(line)),
@@ -528,8 +774,8 @@ def build_digest(sanitized_text: str, *, artifact_id: str, redacted_lines: int)
             "markers": sanitized_text.count("[REDACTED]"),
         },
         "top_error_lines": top_errors,
-        "top_error_receipts": build_top_error_receipts(artifact_id, lines),
-        "duplicate_line_groups": build_duplicate_line_groups(artifact_id, lines),
+        "top_error_receipts": build_top_error_receipts(artifact_id, lines, raw_dir=raw_dir, show_paths=show_paths),
+        "duplicate_line_groups": build_duplicate_line_groups(artifact_id, lines, raw_dir=raw_dir, show_paths=show_paths),
         "representative_head": compact_items(
             lines,
             limit=8,
@@ -572,7 +818,198 @@ def suggested_queries_for(metadata: dict[str, object]) -> list[str]:
     return queries[:MAX_SUGGESTED_QUERIES]
 
 
-def receipt_for(metadata: dict[str, object]) -> dict[str, object]:
+def artifact_handle(artifact_id: str) -> str:
+    return f"contextguard-artifact:{artifact_id}"
+
+
+def compact_stored_output(metadata: dict[str, object]) -> dict[str, object]:
+    stored = metadata.get("stored_output")
+    if not isinstance(stored, dict):
+        return {}
+    compact: dict[str, object] = {}
+    for key in ("scope", "bytes", "lines", "sha256", "content_file", "metadata_file"):
+        if key in stored:
+            compact[key] = stored[key]
+    content_type = metadata.get("content_type")
+    if isinstance(content_type, str):
+        compact["content_type"] = content_type
+    return compact
+
+
+def digest_count(digest: dict[str, object], key: str) -> int:
+    value = digest.get(key)
+    return len(value) if isinstance(value, list) else 0
+
+
+def build_output_sandbox_summary(metadata: dict[str, object]) -> dict[str, object]:
+    digest = metadata.get("digest")
+    if not isinstance(digest, dict):
+        return {"status": "stored"}
+    summary: dict[str, object] = {
+        "status": digest.get("status") or "stored",
+        "top_error_count": digest_count(digest, "top_error_lines"),
+        "top_error_receipt_count": digest_count(digest, "top_error_receipts"),
+        "duplicate_line_group_count": digest_count(digest, "duplicate_line_groups"),
+        "representative_head_count": digest_count(digest, "representative_head"),
+        "representative_tail_count": digest_count(digest, "representative_tail"),
+    }
+    redaction_counts = digest.get("redaction_counts")
+    if isinstance(redaction_counts, dict):
+        summary["redaction_counts"] = {
+            str(key): value
+            for key, value in redaction_counts.items()
+            if isinstance(value, (int, float, str, bool)) or value is None
+        }
+    elif "redacted_lines" in digest:
+        summary["redacted_lines"] = digest.get("redacted_lines")
+    capped = digest.get("capped_for_metadata")
+    if isinstance(capped, bool):
+        summary["capped_for_metadata"] = capped
+    return summary
+
+
+def rehydration_command_record(
+    *,
+    kind: str,
+    cli: str,
+    selector: dict[str, object],
+    exact: bool,
+    note: str | None = None,
+) -> dict[str, object]:
+    record: dict[str, object] = {
+        "type": kind,
+        "selector": selector,
+        "cli": cli,
+        "exact": exact,
+    }
+    if note:
+        record["note"] = note
+    return record
+
+
+def build_output_sandbox_rehydration(
+    metadata: dict[str, object],
+    *,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> dict[str, object]:
+    artifact_id = str(metadata["artifact_id"])
+    cli_exact = artifact_dir_cli_is_exact(raw_dir, show_paths=show_paths)
+    prefix = artifact_dir_cli_prefix(raw_dir, show_paths=show_paths)
+    note = (
+        None
+        if cli_exact
+        else "custom artifact directory is redacted; rerun with the same --dir value or pass --show-paths for a directly executable local command"
+    )
+    commands: list[dict[str, object]] = [
+        rehydration_command_record(
+            kind="metadata",
+            selector={"type": "receipt"},
+            cli=f"{prefix} receipt {artifact_id} --json",
+            exact=cli_exact,
+            note=note,
+        )
+    ]
+
+    retrieval = metadata.get("retrieval")
+    hints = retrieval.get("hints") if isinstance(retrieval, dict) else None
+    if isinstance(hints, list):
+        for hint in hints:
+            if not isinstance(hint, dict):
+                continue
+            hint_type = hint.get("type")
+            selector = hint.get("selector")
+            if not isinstance(selector, dict):
+                selector = {}
+            cli: str | None = None
+            exact = bool(hint.get("exact", True)) and cli_exact
+            if hint_type == "lines":
+                start = selector.get("start")
+                end = selector.get("end")
+                if isinstance(start, int) and isinstance(end, int):
+                    cli = line_query_cli(artifact_id, start, end, raw_dir=raw_dir, show_paths=show_paths)
+            elif hint_type == "pattern":
+                pattern = selector.get("pattern")
+                if isinstance(pattern, str) and pattern:
+                    cli = f"{prefix} get {artifact_id} --pattern {shlex.quote(pattern)}"
+            elif hint_type == "head":
+                max_lines = selector.get("max_lines")
+                if isinstance(max_lines, int) and max_lines > 0:
+                    cli = f"{prefix} get {artifact_id} --max-lines {max_lines}"
+            if cli is None:
+                raw_cli = hint.get("cli")
+                cli = raw_cli if isinstance(raw_cli, str) and raw_cli else None
+            if cli:
+                commands.append(
+                    rehydration_command_record(
+                        kind=str(hint_type or "query"),
+                        selector=selector,
+                        cli=cli,
+                        exact=exact,
+                        note=note if not cli_exact else str(hint.get("note") or "") or None,
+                    )
+                )
+            if len(commands) >= 5:
+                break
+
+    digest = metadata.get("digest")
+    top_error_lines = digest.get("top_error_lines") if isinstance(digest, dict) else None
+    if isinstance(top_error_lines, list):
+        anchor = first_error_anchor("\n".join(str(line) for line in top_error_lines))
+        if anchor and len(commands) < 5:
+            commands.append(
+                rehydration_command_record(
+                    kind="search",
+                    selector={"type": "literal", "pattern": anchor},
+                    cli=f"{prefix} search {shlex.quote(anchor)} --json",
+                    exact=cli_exact,
+                    note=note,
+                )
+            )
+
+    return {
+        "commands": commands,
+        "dir_argument": "default" if default_artifact_dir_requested(raw_dir or DEFAULT_ARTIFACT_DIR) else ("included" if show_paths else "redacted"),
+        "exact_commands": cli_exact,
+        "note": note,
+    }
+
+
+def build_output_sandbox_envelope(
+    metadata: dict[str, object],
+    *,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> dict[str, object]:
+    artifact_id = str(metadata["artifact_id"])
+    return {
+        "schema_version": OUTPUT_SANDBOX_SCHEMA_VERSION,
+        "mode": "local_artifact_receipt",
+        "handle": artifact_handle(artifact_id),
+        "artifact_id": artifact_id,
+        "stored_output": compact_stored_output(metadata),
+        "summary": build_output_sandbox_summary(metadata),
+        "rehydration": build_output_sandbox_rehydration(metadata, raw_dir=raw_dir, show_paths=show_paths),
+        "agent_guidance": [
+            "Keep this compact receipt in agent context instead of pasting the full output.",
+            "Before relying on omitted details, rehydrate the exact sanitized slice with one of rehydration.commands[].cli.",
+            "For repeated diagnostics, query narrower lines or literal matches instead of rerunning broad commands unchanged.",
+        ],
+        "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,
+        },
+    }
+
+
+def receipt_for(
+    metadata: dict[str, object],
+    *,
+    raw_dir: str | None = None,
+    show_paths: bool = False,
+) -> dict[str, object]:
     artifact_id = str(metadata["artifact_id"])
     return {
         "artifact_id": artifact_id,
@@ -585,11 +1022,12 @@ def receipt_for(metadata: dict[str, object]) -> dict[str, object]:
         "digest": metadata.get("digest"),
         "retrieval": metadata.get("retrieval"),
         "available_queries": [
-            f"context-guard-artifact get {artifact_id} --lines 1:80",
-            f"context-guard-artifact get {artifact_id} --pattern ERROR --max-lines 40",
-            f"context-guard-artifact get {artifact_id} --json --lines 1:20",
+            line_query_cli(artifact_id, 1, 80, raw_dir=raw_dir, show_paths=show_paths),
+            f"{artifact_dir_cli_prefix(raw_dir, show_paths=show_paths)} get {artifact_id} --pattern ERROR --max-lines 40",
+            f"{artifact_dir_cli_prefix(raw_dir, show_paths=show_paths)} get {artifact_id} --json --lines 1:20",
         ],
         "suggested_queries": suggested_queries_for(metadata),
+        "output_sandbox": build_output_sandbox_envelope(metadata, raw_dir=raw_dir, show_paths=show_paths),
     }
 
 
@@ -699,7 +1137,13 @@ def store_command(args: argparse.Namespace) -> int:
             "content_file": content_path.name,
             "metadata_file": meta_path.name,
         },
-        "digest": build_digest(sanitized_text, artifact_id=artifact_id, redacted_lines=redacted_lines),
+        "digest": build_digest(
+            sanitized_text,
+            artifact_id=artifact_id,
+            redacted_lines=redacted_lines,
+            raw_dir=args.dir,
+            show_paths=args.show_paths,
+        ),
         "retrieval": {
             "strategy": strategy,
             "deterministic": True,
@@ -709,17 +1153,22 @@ def store_command(args: argparse.Namespace) -> int:
                 content_type=content_type,
                 strategy=strategy,
                 total_lines=total_lines,
+                raw_dir=args.dir,
+                show_paths=args.show_paths,
             ),
         },
     }
     shrink_digest_for_metadata_cap(metadata)
     write_private_text(content_path, sanitized_text)
     write_private_text(meta_path, metadata_json_text(metadata))
-    receipt = receipt_for(metadata)
+    receipt = receipt_for(metadata, raw_dir=args.dir, show_paths=args.show_paths)
     if args.json:
         print(json.dumps(receipt, ensure_ascii=False, indent=2, sort_keys=True))
     else:
         print(f"artifact_id={artifact_id}")
+        sandbox = receipt.get("output_sandbox")
+        handle = sandbox.get("handle") if isinstance(sandbox, dict) else artifact_handle(artifact_id)
+        print(f"handle={handle}")
         stored = receipt["stored_output"]
         if isinstance(stored, dict):
             print(f"stored_output={stored.get('lines')} lines/{stored.get('bytes')} bytes")
@@ -728,7 +1177,16 @@ def store_command(args: argparse.Namespace) -> int:
             print("top_error_lines:")
             for line in digest["top_error_lines"]:  # type: ignore[index]
                 print(f"- {line}")
-        print(f"query=context-guard-artifact get {artifact_id} --lines 1:80")
+        available_queries = receipt.get("available_queries")
+        if isinstance(available_queries, list) and available_queries:
+            print(f"query={available_queries[0]}")
+        rehydration = sandbox.get("rehydration") if isinstance(sandbox, dict) else None
+        commands = rehydration.get("commands") if isinstance(rehydration, dict) else None
+        if isinstance(commands, list):
+            for command in commands:
+                if isinstance(command, dict) and command.get("type") != "metadata" and isinstance(command.get("cli"), str):
+                    print(f"rehydrate={command['cli']}")
+                    break
     return 0
 
 
@@ -745,6 +1203,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 +1244,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 +1426,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 +1435,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 +1466,176 @@ def get_command(args: argparse.Namespace) -> int:
     return 0
 
 
+def receipt_command(args: argparse.Namespace) -> int:
+    artifact_id = args.artifact_id
+    try:
+        last_missing: FileNotFoundError | None = None
+        for directory in artifact_read_directories(args.dir):
+            try:
+                metadata, _content_path, _content = load_verified_artifact(directory, artifact_id)
+                break
+            except FileNotFoundError as exc:
+                last_missing = exc
+        else:
+            if last_missing is not None:
+                raise last_missing
+            raise FileNotFoundError(f"artifact not found: {artifact_id}")
+        receipt = receipt_for(metadata, raw_dir=args.dir, show_paths=bool(getattr(args, "show_paths", False)))
+    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(receipt, ensure_ascii=False, indent=2, sort_keys=True))
+    else:
+        sandbox = receipt.get("output_sandbox")
+        handle = sandbox.get("handle") if isinstance(sandbox, dict) else artifact_handle(artifact_id)
+        print(f"artifact_id={artifact_id}")
+        print(f"handle={handle}")
+        stored = receipt.get("stored_output")
+        if isinstance(stored, dict):
+            print(f"stored_output={stored.get('lines')} lines/{stored.get('bytes')} bytes")
+        rehydration = sandbox.get("rehydration") if isinstance(sandbox, dict) else None
+        commands = rehydration.get("commands") if isinstance(rehydration, dict) else None
+        if isinstance(commands, list):
+            for command in commands[:4]:
+                if isinstance(command, dict) and command.get("cli"):
+                    print(f"rehydrate={command.get('cli')}")
+        print("claim_boundary=local sanitized artifact; no hosted token/cost savings claim")
+    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()
@@ -874,7 +1654,7 @@ def list_command(args: argparse.Namespace) -> int:
                 continue
             artifact_id = str(data.get("artifact_id", "")) if isinstance(data, dict) else ""
             if isinstance(data, dict) and ARTIFACT_ID_RE.fullmatch(artifact_id) and artifact_id not in seen:
-                items.append(receipt_for(data))
+                items.append(receipt_for(data, raw_dir=args.dir, show_paths=False))
                 seen.add(artifact_id)
     items.sort(key=lambda item: str(item.get("artifact_id", "")))
     if args.json:
@@ -915,9 +1695,34 @@ def build_parser() -> argparse.ArgumentParser:
     get.add_argument("--json", action="store_true", help="emit query JSON with content")
     get.set_defaults(func=get_command)
 
+    receipt = subparsers.add_parser("receipt", help="print metadata-only receipt and rehydration handle for a stored artifact")
+    receipt.add_argument("artifact_id")
+    receipt.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",
+    )
+    receipt.add_argument("--json", action="store_true", help="emit receipt JSON without artifact content")
+    receipt.set_defaults(func=receipt_command)
+
     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