@ictechgy/context-guard 0.4.10 → 0.4.12

package/plugins/context-guard/bin/context-guard-trim-output

@@ -7,10 +7,9 @@ lines into the conversation while preserving the lines most likely to be useful.
 from __future__ import annotations
 
 import argparse
+import codecs
 import collections
 import hashlib
-import importlib.machinery
-import importlib.util
 import json
 import os
 from pathlib import Path, PurePosixPath
@@ -18,11 +17,14 @@ import queue
 import re
 import shlex
 import signal
+import stat
 import subprocess
 import sys
+import tempfile
 import threading
 import time
-from typing import Iterable, Iterator
+import types
+from typing import BinaryIO, Iterable, Iterator
 
 MAX_SUMMARY_ITEM_CHARS = 500
 MAX_LINES_LIMIT = 5_000
@@ -35,6 +37,10 @@ MAX_TIMEOUT_SECONDS = 86_400
 TIMEOUT_EXIT_CODE = 124
 DEFAULT_ARTIFACT_RECEIPT_MAX_BYTES = 10_000_000
 MAX_ARTIFACT_RECEIPT_MAX_BYTES = 100_000_000
+COMMAND_READ_CHUNK_BYTES = 64 * 1024
+COMMAND_MAX_UNTERMINATED_LINE_CHARS = 4_096
+RAW_TRUNCATION_REDACTION_HOLDBACK_CHARS = 1_024
+MAX_DYNAMIC_SIBLING_MODULE_BYTES = 2_000_000
 
 
 def bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
@@ -132,6 +138,10 @@ def anonymize_absolute_paths(text: str) -> str:
     return ABSOLUTE_PATH_RE.sub(repl, text)
 
 
+class UnsafeAdjacentModuleError(RuntimeError):
+    """Adjacent helper exists but cannot be trusted for dynamic loading."""
+
+
 class FallbackLineSanitizer:
     def __init__(self, *, show_paths: bool = False, diagnostic: str | None = None) -> None:
         self.show_paths = show_paths
@@ -159,24 +169,82 @@ class FallbackLineSanitizer:
         return line, redacted
 
 
+def no_follow_file_flags() -> int:
+    if not hasattr(os, "O_NOFOLLOW"):
+        raise UnsafeAdjacentModuleError("O_NOFOLLOW is required for adjacent helper loads")
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    return flags
+
+
+def no_follow_dir_flags() -> int:
+    flags = no_follow_file_flags()
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    return flags
+
+
+def read_adjacent_module_source(script_dir: Path, name: str, *, max_bytes: int) -> str | None:
+    if name in {"", ".", ".."} or "/" in name or os.sep in name:
+        raise RuntimeError(f"invalid adjacent helper name: {name!r}")
+    try:
+        dir_fd = os.open(str(script_dir), no_follow_dir_flags())
+    except OSError as exc:
+        raise UnsafeAdjacentModuleError(f"could not inspect helper directory: {exc}") from exc
+    try:
+        try:
+            fd = os.open(name, no_follow_file_flags(), dir_fd=dir_fd)
+        except FileNotFoundError:
+            return None
+        except OSError as exc:
+            raise UnsafeAdjacentModuleError(f"{name} could not be opened without following symlinks: {exc}") from exc
+        try:
+            st = os.fstat(fd)
+            if not stat.S_ISREG(st.st_mode):
+                raise UnsafeAdjacentModuleError(f"{name} is not a regular helper file")
+            if st.st_size > max_bytes:
+                raise UnsafeAdjacentModuleError(f"{name} exceeds helper size cap: {st.st_size} > {max_bytes}")
+            data = os.read(fd, max_bytes + 1)
+        finally:
+            os.close(fd)
+    finally:
+        os.close(dir_fd)
+    if len(data) > max_bytes:
+        raise UnsafeAdjacentModuleError(f"{name} exceeds helper size cap: > {max_bytes}")
+    return data.decode("utf-8", errors="replace")
+
+
+def load_adjacent_python_module(script_dir: Path, name: str, *, module_prefix: str) -> object | None:
+    source = read_adjacent_module_source(script_dir, name, max_bytes=MAX_DYNAMIC_SIBLING_MODULE_BYTES)
+    if source is None:
+        return None
+    module_name = f"{module_prefix}_{os.getpid()}_{hashlib.sha256(name.encode('utf-8')).hexdigest()[:12]}"
+    module = types.ModuleType(module_name)
+    module.__file__ = str(script_dir / name)
+    module.__package__ = ""
+    exec(compile(source, str(script_dir / name), "exec"), module.__dict__)
+    return module
+
+
 def load_line_sanitizer(show_paths: bool) -> object:
     """Reuse the stronger sanitizer when it is shipped next to this wrapper."""
-    script_dir = os.path.dirname(os.path.abspath(__file__))
+    script_dir = Path(__file__).resolve().parent
     load_errors: list[str] = []
     for name in ("sanitize_output.py", "context-guard-sanitize-output"):
-        candidate = os.path.join(script_dir, name)
-        if not os.path.exists(candidate):
-            continue
         try:
-            loader = importlib.machinery.SourceFileLoader(f"_claude_token_sanitize_{os.getpid()}", candidate)
-            spec = importlib.util.spec_from_loader(loader.name, loader)
-            if spec is None:
+            module = load_adjacent_python_module(
+                script_dir,
+                name,
+                module_prefix="_claude_token_sanitize",
+            )
+            if module is None:
                 continue
-            module = importlib.util.module_from_spec(spec)
-            loader.exec_module(module)
             return module.LineSanitizer(show_paths=show_paths)
+        except UnsafeAdjacentModuleError:
+            raise
         except Exception as exc:
-            load_errors.append(f"{os.path.basename(candidate)} failed to load: {exc.__class__.__name__}: {exc}")
+            load_errors.append(f"{name} failed to load: {exc.__class__.__name__}: {exc}")
             continue
     diagnostic = "; ".join(load_errors) if load_errors else "strong sanitizer not found next to trim wrapper"
     return FallbackLineSanitizer(show_paths=show_paths, diagnostic=diagnostic)
@@ -189,22 +257,22 @@ def load_artifact_store_module() -> object:
     wrapper must resolve both source-tree (`context_escrow.py`) and packaged
     (`context-guard-artifact`) names.
     """
-    script_dir = os.path.dirname(os.path.abspath(__file__))
+    script_dir = Path(__file__).resolve().parent
     load_errors: list[str] = []
     for name in ("context_escrow.py", "context-guard-artifact", "claude-token-artifact"):
-        candidate = os.path.join(script_dir, name)
-        if not os.path.exists(candidate):
-            continue
         try:
-            loader = importlib.machinery.SourceFileLoader(f"_context_guard_artifact_{os.getpid()}", candidate)
-            spec = importlib.util.spec_from_loader(loader.name, loader)
-            if spec is None:
+            module = load_adjacent_python_module(
+                script_dir,
+                name,
+                module_prefix="_context_guard_artifact",
+            )
+            if module is None:
                 continue
-            module = importlib.util.module_from_spec(spec)
-            loader.exec_module(module)
             return module
+        except UnsafeAdjacentModuleError:
+            raise
         except Exception as exc:
-            load_errors.append(f"{os.path.basename(candidate)} failed to load: {exc.__class__.__name__}: {exc}")
+            load_errors.append(f"{name} failed to load: {exc.__class__.__name__}: {exc}")
             continue
     diagnostic = "; ".join(load_errors) if load_errors else "artifact store not found next to trim wrapper"
     raise RuntimeError(diagnostic)
@@ -272,7 +340,13 @@ def store_sanitized_artifact_receipt(
             "metadata_file": meta_path.name,
             "scope": "sanitized_full_output",
         },
-        "digest": artifact.build_digest(sanitized_text, artifact_id=artifact_id, redacted_lines=redacted_lines),
+        "digest": artifact.build_digest(
+            sanitized_text,
+            artifact_id=artifact_id,
+            redacted_lines=redacted_lines,
+            raw_dir=str(getattr(args, "artifact_dir", ".context-guard/artifacts")),
+            show_paths=bool(getattr(args, "show_paths", False)),
+        ),
         "retrieval": {
             "strategy": strategy,
             "deterministic": True,
@@ -282,13 +356,17 @@ def store_sanitized_artifact_receipt(
                 content_type=content_type,
                 strategy=strategy,
                 total_lines=total_lines,
+                raw_dir=str(getattr(args, "artifact_dir", ".context-guard/artifacts")),
+                show_paths=bool(getattr(args, "show_paths", False)),
             ),
         },
     }
     artifact.shrink_digest_for_metadata_cap(metadata)
     artifact.write_private_text(content_path, sanitized_text)
     artifact.write_private_text(meta_path, artifact.metadata_json_text(metadata))
-    receipt = artifact.receipt_for(metadata)
+    raw_artifact_dir = str(getattr(args, "artifact_dir", ".context-guard/artifacts"))
+    show_artifact_paths = bool(getattr(args, "show_paths", False))
+    receipt = artifact.receipt_for(metadata, raw_dir=raw_artifact_dir, show_paths=show_artifact_paths)
     query_line_cap = int(getattr(artifact, "MAX_QUERY_LINES", 5_000))
     query_char_cap = 1_000_000
     content_chars = len(sanitized_text)
@@ -301,21 +379,19 @@ def store_sanitized_artifact_receipt(
         "reason": "artifact query cap exceeded; use retrieval hints for exact slices",
     }
     if total_lines <= query_line_cap and content_chars <= query_char_cap:
-        raw_artifact_dir = str(getattr(args, "artifact_dir", ".context-guard/artifacts"))
-        dir_flags = ""
-        if raw_artifact_dir != ".context-guard/artifacts":
-            dir_flags = f" --dir {shlex.quote(raw_artifact_dir)}"
         line_flags = ""
         if total_lines > 0:
             line_flags = f" --lines 1:{total_lines} --max-lines {max(1, total_lines)}"
+        prefix = artifact.artifact_dir_cli_prefix(raw_artifact_dir, show_paths=show_artifact_paths)
         exact_reexpand = {
             "available": True,
             "scope": "sanitized_full_output",
             "sha256": content_sha,
             "bytes": content_bytes,
             "lines": total_lines,
+            "exact": artifact.artifact_dir_cli_is_exact(raw_artifact_dir, show_paths=show_artifact_paths),
             "cli": (
-                f"context-guard-artifact{dir_flags} get {artifact_id}{line_flags} "
+                f"{prefix} get {artifact_id}{line_flags} "
                 f"--max-chars {max(1, content_chars)}"
             ),
         }
@@ -323,23 +399,75 @@ def store_sanitized_artifact_receipt(
     return receipt
 
 
-def capture_sanitized_artifact_line(
-    *,
-    capture_enabled: bool,
-    sanitized_line: str,
-    artifact_lines: list[str],
-    capture_bytes: int,
-    capture_overflow: bool,
-    max_bytes: int,
-) -> tuple[int, bool]:
-    if not capture_enabled or capture_overflow:
-        return capture_bytes, capture_overflow
-    source_bytes = len(sanitized_line.encode("utf-8", errors="replace"))
-    if capture_bytes + source_bytes <= max_bytes:
-        artifact_lines.append(sanitized_line)
-        return capture_bytes + source_bytes, False
-    artifact_lines.clear()
-    return capture_bytes, True
+class SanitizedArtifactCapture:
+    def __init__(self, *, enabled: bool, max_bytes: int) -> None:
+        self.enabled = enabled
+        self.max_bytes = max_bytes
+        self.bytes = 0
+        self.overflow = False
+        self.error: str | None = None
+        self._file: BinaryIO | None = None
+
+    def _ensure_file(self) -> BinaryIO | None:
+        if self._file is not None:
+            return self._file
+        try:
+            self._file = tempfile.TemporaryFile("w+b")
+        except OSError as exc:
+            self._record_error(exc)
+            return None
+        return self._file
+
+    def _record_error(self, exc: OSError) -> None:
+        if self.error is None:
+            self.error = f"{exc.__class__.__name__}: {exc}"
+
+    def add(self, sanitized_line: str) -> None:
+        if not self.enabled or self.overflow or self.error:
+            return
+        encoded = sanitized_line.encode("utf-8", errors="replace")
+        source_bytes = len(encoded)
+        if self.bytes + source_bytes > self.max_bytes:
+            self.overflow = True
+            self.close()
+            return
+        target = self._ensure_file()
+        if target is None:
+            return
+        try:
+            target.write(encoded)
+        except OSError as exc:
+            self._record_error(exc)
+            self.close()
+            return
+        self.bytes += source_bytes
+
+    def text(self) -> str:
+        if self._file is None:
+            return ""
+        try:
+            self._file.flush()
+            self._file.seek(0)
+            return self._file.read().decode("utf-8", errors="replace")
+        except OSError as exc:
+            self._record_error(exc)
+            self.close()
+            return ""
+
+    def close(self) -> None:
+        target = self._file
+        self._file = None
+        if target is not None:
+            try:
+                target.close()
+            except OSError as exc:
+                self._record_error(exc)
+
+    def __enter__(self) -> "SanitizedArtifactCapture":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
 
 
 def unique_keep_order(lines: Iterable[str]) -> list[str]:
@@ -720,11 +848,33 @@ def build_digest_payload(
 
 
 def markdown_artifact_receipt_lines(artifact_receipt: dict[str, object]) -> list[str]:
+    sandbox = artifact_receipt.get("output_sandbox")
+    handle = None
+    rehydrate = None
+    if isinstance(sandbox, dict):
+        raw_handle = sandbox.get("handle")
+        if isinstance(raw_handle, str):
+            handle = raw_handle
+        rehydration = sandbox.get("rehydration")
+        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):
+                    rehydrate = command["cli"]
+                    break
+            if rehydrate is None:
+                for command in commands:
+                    if isinstance(command, dict) and isinstance(command.get("cli"), str):
+                        rehydrate = command["cli"]
+                        break
     lines = [
         "- artifact_receipt: "
         f"stored={str(artifact_receipt.get('stored')).lower()} "
-        f"id={artifact_receipt.get('artifact_id') or artifact_receipt.get('error')}\n"
+        f"id={artifact_receipt.get('artifact_id') or artifact_receipt.get('error')}"
+        f"{(' handle=' + handle) if handle else ''}\n"
     ]
+    if rehydrate:
+        lines.append(f"- rehydrate: `{rehydrate}`\n")
     exact = artifact_receipt.get("exact_reexpand")
     if isinstance(exact, dict) and exact.get("cli"):
         lines.append(f"- exact_reexpand: `{exact.get('cli')}`\n")
@@ -742,12 +892,16 @@ def compact_markdown_artifact_receipt(payload: dict[str, object], max_chars: int
 
     artifact_id = artifact_receipt.get("artifact_id") or artifact_receipt.get("error")
     stored = str(artifact_receipt.get("stored")).lower()
+    sandbox = artifact_receipt.get("output_sandbox")
+    handle = sandbox.get("handle") if isinstance(sandbox, dict) and isinstance(sandbox.get("handle"), str) else None
     exact = artifact_receipt.get("exact_reexpand")
     exact_available = ""
     if isinstance(exact, dict) and "available" in exact:
         exact_available = f" exact_available={str(exact.get('available')).lower()}"
 
     candidates = [
+        f"- artifact_receipt: stored={stored} id={artifact_id}{(' handle=' + handle) if handle else ''}{exact_available}; use output_sandbox.rehydration for exact slices\n",
+        f"- artifact_receipt: stored={stored} id={artifact_id}{(' handle=' + handle) if handle else ''}{exact_available}\n",
         f"- artifact_receipt: stored={stored} id={artifact_id}{exact_available}; raise --max-chars for full exact_reexpand\n",
         f"- artifact_receipt: stored={stored} id={artifact_id}{exact_available}\n",
         f"- artifact_receipt: id={artifact_id}\n",
@@ -905,15 +1059,67 @@ def render_digest_json(payload: dict[str, object], max_chars: int) -> str:
                 for key in ("scope", "bytes", "lines", "sha256")
                 if key in stored_output
             }
+        sandbox = artifact_receipt.get("output_sandbox")
+        if isinstance(sandbox, dict):
+            compact_sandbox: dict[str, object] = {
+                key: sandbox[key]
+                for key in ("schema_version", "mode", "handle", "artifact_id")
+                if key in sandbox
+            }
+            rehydration = sandbox.get("rehydration")
+            if isinstance(rehydration, dict):
+                commands = rehydration.get("commands")
+                if isinstance(commands, list):
+                    kept_commands = [
+                        command
+                        for command in commands
+                        if isinstance(command, dict) and isinstance(command.get("cli"), str)
+                    ][:2]
+                    compact_sandbox["rehydration"] = {
+                        "commands": kept_commands,
+                        "exact_commands": rehydration.get("exact_commands"),
+                        "dir_argument": rehydration.get("dir_argument"),
+                    }
+            compact["output_sandbox"] = compact_sandbox
         exact = artifact_receipt.get("exact_reexpand")
         if include_exact_reexpand and isinstance(exact, dict):
             compact["exact_reexpand"] = {
                 key: exact[key]
-                for key in ("available", "scope", "sha256", "bytes", "lines", "cli", "reason")
+                for key in ("available", "scope", "sha256", "bytes", "lines", "exact", "cli", "reason")
                 if key in exact
             }
         return compact
 
+    def tiny_artifact_receipt() -> dict[str, object] | None:
+        artifact_receipt = payload.get("artifact_receipt")
+        if not isinstance(artifact_receipt, dict):
+            return None
+        compact: dict[str, object] = {}
+        for key in ("stored", "artifact_id", "error"):
+            if key in artifact_receipt:
+                compact[key] = artifact_receipt[key]
+        sandbox = artifact_receipt.get("output_sandbox")
+        if isinstance(sandbox, dict):
+            tiny_sandbox: dict[str, object] = {}
+            handle = sandbox.get("handle")
+            if isinstance(handle, str):
+                tiny_sandbox["handle"] = handle
+            rehydration = sandbox.get("rehydration")
+            commands = rehydration.get("commands") if isinstance(rehydration, dict) else None
+            if isinstance(commands, list):
+                for command in commands:
+                    if isinstance(command, dict) and isinstance(command.get("cli"), str):
+                        tiny_sandbox["rehydration"] = {
+                            "commands": [{
+                                "type": command.get("type"),
+                                "cli": command.get("cli"),
+                            }]
+                        }
+                        break
+            if tiny_sandbox:
+                compact["output_sandbox"] = tiny_sandbox
+        return compact
+
     def attach_artifact_receipt(candidate: dict[str, object], artifact_receipt: dict[str, object] | None) -> dict[str, object]:
         if artifact_receipt is not None:
             candidate["artifact_receipt"] = artifact_receipt
@@ -955,6 +1161,7 @@ def render_digest_json(payload: dict[str, object], max_chars: int) -> str:
         }
     compact_receipt = compact_artifact_receipt(include_exact_reexpand=True)
     minimal_receipt = compact_artifact_receipt(include_exact_reexpand=False)
+    tiny_receipt = tiny_artifact_receipt()
 
     return first_fitting(
         [
@@ -1004,6 +1211,15 @@ def render_digest_json(payload: dict[str, object], max_chars: int) -> str:
                 },
                 minimal_receipt,
             ),
+            attach_artifact_receipt(
+                {
+                    "digest_capped": True,
+                    "status": payload.get("status"),
+                    "exit_code": payload.get("exit_code"),
+                    "timed_out": payload.get("timed_out"),
+                },
+                tiny_receipt,
+            ),
             {"digest_capped": True},
         ]
     )
@@ -1081,14 +1297,16 @@ def terminate_process_tree(
 class TimedCommandStream:
     def __init__(
         self,
-        proc: subprocess.Popen[str],
-        stdout: Iterable[str],
+        proc: subprocess.Popen[bytes],
+        stdout: BinaryIO,
         *,
         timeout_seconds: int,
+        max_line_chars: int = MAX_LINE_CHARS_LIMIT,
         process_group_id: int | None = None,
     ) -> None:
         self.proc = proc
         self.timeout_seconds = timeout_seconds
+        self.max_unterminated_line_chars = max(1, max_line_chars)
         self.process_group_id = process_group_id
         self.deadline = time.monotonic() + timeout_seconds
         self.timed_out = False
@@ -1098,10 +1316,62 @@ class TimedCommandStream:
         self._thread = threading.Thread(target=self._read_stdout, args=(stdout,), daemon=True)
         self._thread.start()
 
-    def _read_stdout(self, stdout: Iterable[str]) -> None:
+    def _truncated_raw_line(self, text: str) -> str:
+        holdback = min(RAW_TRUNCATION_REDACTION_HOLDBACK_CHARS, self.max_unterminated_line_chars)
+        safe_keep = max(0, self.max_unterminated_line_chars - holdback)
+        return (
+            text[:safe_keep]
+            + (
+                "...[context-guard-kit: raw line truncated before newline "
+                f"after {self.max_unterminated_line_chars} chars; "
+                f"withheld {holdback} boundary chars for redaction safety]\n"
+            )
+        )
+
+    def _read_stdout(self, stdout: BinaryIO) -> None:
+        decoder = codecs.getincrementaldecoder("utf-8")("replace")
+        pending = ""
+        discarding_oversized_line = False
+
+        def feed(text: str) -> None:
+            nonlocal pending, discarding_oversized_line
+            if not text:
+                return
+            pending += text
+            while pending:
+                if discarding_oversized_line:
+                    newline_index = pending.find("\n")
+                    if newline_index == -1:
+                        pending = ""
+                        return
+                    pending = pending[newline_index + 1 :]
+                    discarding_oversized_line = False
+                    continue
+
+                newline_index = pending.find("\n")
+                if newline_index != -1:
+                    if newline_index > self.max_unterminated_line_chars:
+                        self._queue.put(self._truncated_raw_line(pending))
+                    else:
+                        self._queue.put(pending[: newline_index + 1])
+                    pending = pending[newline_index + 1 :]
+                    continue
+
+                if len(pending) > self.max_unterminated_line_chars:
+                    self._queue.put(self._truncated_raw_line(pending))
+                    pending = ""
+                    discarding_oversized_line = True
+                return
+
         try:
-            for line in stdout:
-                self._queue.put(line)
+            while True:
+                chunk = stdout.read(COMMAND_READ_CHUNK_BYTES)
+                if not chunk:
+                    break
+                feed(decoder.decode(chunk, final=False))
+            feed(decoder.decode(b"", final=True))
+            if pending and not discarding_oversized_line:
+                self._queue.put(pending)
         finally:
             self._stream_closed = True
             self._queue.put(_STREAM_END)
@@ -1242,6 +1512,18 @@ def main() -> int:
     if args.artifact_receipt and args.digest == "off":
         print("trim_command_output.py: --artifact-receipt requires --digest markdown or --digest json", file=sys.stderr)
         return 2
+    if args.artifact_receipt:
+        try:
+            load_artifact_store_module()
+        except UnsafeAdjacentModuleError as exc:
+            print(f"context-guard-kit: unsafe adjacent helper: {exc}", file=sys.stderr)
+            return 2
+        except Exception:
+            # Missing/broken artifact helpers are reported in the digest payload as
+            # artifact_receipt_unavailable for backward compatibility. Integrity
+            # failures above are different: they indicate an adjacent helper exists
+            # but cannot be safely trusted, so they fail closed.
+            pass
 
     command = args.command
     if command and command[0] == "--":
@@ -1250,6 +1532,12 @@ def main() -> int:
         print("trim_command_output.py: missing command", file=sys.stderr)
         return 2
 
+    try:
+        line_sanitizer = load_line_sanitizer(args.show_paths)
+    except UnsafeAdjacentModuleError as exc:
+        print(f"context-guard-kit: unsafe adjacent helper: {exc}", file=sys.stderr)
+        return 2
+
     popen_kwargs: dict[str, object] = {}
     if os.name != "nt":
         popen_kwargs["start_new_session"] = True
@@ -1258,9 +1546,8 @@ def main() -> int:
             command,
             stdout=subprocess.PIPE,
             stderr=subprocess.STDOUT,
-            text=True,
-            bufsize=1,
-            errors="replace",
+            text=False,
+            bufsize=0,
             **popen_kwargs,
         )
     except OSError as exc:
@@ -1276,20 +1563,19 @@ def main() -> int:
     visible_chars = 0
     any_line_capped = False
     runner_summary = RunnerFailureSummary(args.runner_summary_items, show_paths=args.show_paths)
-    line_sanitizer = load_line_sanitizer(args.show_paths)
     duplicate_tracker = DuplicateLineTracker()
     redacted_lines = 0
-    artifact_lines: list[str] = []
-    artifact_capture_bytes = 0
-    artifact_capture_overflow = False
+    artifact_capture = SanitizedArtifactCapture(enabled=args.artifact_receipt, max_bytes=args.artifact_max_bytes)
 
     if proc.stdout is None:
+        artifact_capture.close()
         print("trim_command_output.py: subprocess produced no stdout pipe", file=sys.stderr)
         return 1
     command_stream = TimedCommandStream(
         proc,
         proc.stdout,
         timeout_seconds=args.timeout_seconds,
+        max_line_chars=COMMAND_MAX_UNTERMINATED_LINE_CHARS,
         process_group_id=process_group_id_for(proc),
     )
     for line in command_stream:
@@ -1298,14 +1584,7 @@ def main() -> int:
         visible_source, redacted = line_sanitizer.sanitize(line)  # type: ignore[attr-defined]
         if redacted:
             redacted_lines += 1
-        artifact_capture_bytes, artifact_capture_overflow = capture_sanitized_artifact_line(
-            capture_enabled=args.artifact_receipt,
-            sanitized_line=visible_source,
-            artifact_lines=artifact_lines,
-            capture_bytes=artifact_capture_bytes,
-            capture_overflow=artifact_capture_overflow,
-            max_bytes=args.artifact_max_bytes,
-        )
+        artifact_capture.add(visible_source)
         visible_line, line_capped = cap_line(visible_source, args.max_line_chars)
         any_line_capped = any_line_capped or line_capped
         visible_chars += len(visible_line)
@@ -1328,14 +1607,7 @@ def main() -> int:
         visible_source, redacted = line_sanitizer.sanitize(line)  # type: ignore[attr-defined]
         if redacted:
             redacted_lines += 1
-        artifact_capture_bytes, artifact_capture_overflow = capture_sanitized_artifact_line(
-            capture_enabled=args.artifact_receipt,
-            sanitized_line=visible_source,
-            artifact_lines=artifact_lines,
-            capture_bytes=artifact_capture_bytes,
-            capture_overflow=artifact_capture_overflow,
-            max_bytes=args.artifact_max_bytes,
-        )
+        artifact_capture.add(visible_source)
         visible_line, line_capped = cap_line(visible_source, args.max_line_chars)
         any_line_capped = any_line_capped or line_capped
         visible_chars += len(visible_line)
@@ -1368,33 +1640,64 @@ def main() -> int:
             duplicate_line_groups=duplicate_tracker.as_list(),
         )
         if args.artifact_receipt:
-            if artifact_capture_overflow:
+            if artifact_capture.overflow:
                 payload["artifact_receipt"] = {
                     "stored": False,
                     "error": "sanitized_output_exceeds_artifact_max_bytes",
                     "max_bytes": args.artifact_max_bytes,
                     "exact_reexpand": {"available": False, "reason": "artifact size cap exceeded"},
                 }
+            elif artifact_capture.error:
+                payload["artifact_receipt"] = {
+                    "stored": False,
+                    "error": "artifact_receipt_capture_unavailable",
+                    "reason": artifact_capture.error,
+                    "exact_reexpand": {"available": False, "reason": "artifact receipt capture unavailable"},
+                }
             else:
-                try:
-                    payload["artifact_receipt"] = store_sanitized_artifact_receipt(
-                        sanitized_text="".join(artifact_lines),
-                        command=command,
-                        args=args,
-                        line_sanitizer=line_sanitizer,
-                        redacted_lines=redacted_lines,
-                    )
-                except Exception as exc:
+                sanitized_artifact_text = artifact_capture.text()
+                if artifact_capture.error:
                     payload["artifact_receipt"] = {
                         "stored": False,
-                        "error": "artifact_receipt_unavailable",
-                        "reason": f"{exc.__class__.__name__}: {exc}",
-                        "exact_reexpand": {"available": False, "reason": "artifact receipt unavailable"},
+                        "error": "artifact_receipt_capture_unavailable",
+                        "reason": artifact_capture.error,
+                        "exact_reexpand": {"available": False, "reason": "artifact receipt capture unavailable"},
                     }
+                else:
+                    try:
+                        payload["artifact_receipt"] = store_sanitized_artifact_receipt(
+                            sanitized_text=sanitized_artifact_text,
+                            command=command,
+                            args=args,
+                            line_sanitizer=line_sanitizer,
+                            redacted_lines=redacted_lines,
+                        )
+                    except UnsafeAdjacentModuleError as exc:
+                        artifact_capture.close()
+                        print(f"context-guard-kit: unsafe adjacent helper: {exc}", file=sys.stderr)
+                        return 2
+                    except Exception as exc:
+                        payload["artifact_receipt"] = {
+                            "stored": False,
+                            "error": "artifact_receipt_unavailable",
+                            "reason": f"{exc.__class__.__name__}: {exc}",
+                            "exact_reexpand": {"available": False, "reason": "artifact receipt unavailable"},
+                        }
+            artifact_receipt = payload.get("artifact_receipt")
+            if isinstance(artifact_receipt, dict) and artifact_receipt.get("stored"):
+                next_queries = payload.setdefault("next_queries", [])
+                if isinstance(next_queries, list):
+                    guidance = (
+                        "Use artifact_receipt.output_sandbox.rehydration commands for exact sanitized slices "
+                        "before rerunning the broad command or requesting full raw output."
+                    )
+                    if guidance not in next_queries:
+                        next_queries.insert(0, guidance)
         if args.digest == "json":
             sys.stdout.write(render_digest_json(payload, args.max_chars))
         else:
             sys.stdout.write(render_digest_markdown(payload, args.max_chars))
+        artifact_capture.close()
         return rc
 
     if total <= args.max_lines and visible_chars <= args.max_chars and not any_line_capped:
@@ -1442,6 +1745,7 @@ def main() -> int:
             output += "[context-guard-kit] final summary was capped by --max-chars.\n"
         sys.stdout.write(output)
 
+    artifact_capture.close()
     return rc