@ictechgy/context-guard 0.4.9 → 0.4.10

package/plugins/context-guard/bin/context-guard-pack

@@ -43,6 +43,8 @@ SUGGEST_SCHEMA_VERSION = "contextguard.pack-suggest.v1"
 AUTO_SCHEMA_VERSION = "contextguard.pack-auto.v1"
 AUTO_EXPLAIN_SCHEMA_VERSION = "contextguard.pack-auto-explain.v1"
 REPO_MAP_SCHEMA_VERSION = "contextguard.pack-repo-map.v1"
+ADAPTIVE_K_SCHEMA_VERSION = "contextguard.pack-adaptive-k.v1"
+SYMBOL_MEMORY_SCHEMA_VERSION = "contextguard.pack-symbol-memory.v1"
 DEFAULT_SUGGEST_TOP = 8
 MAX_SUGGEST_TOP = 50
 DEFAULT_SUGGEST_CONTEXT_LINES = 20
@@ -52,14 +54,22 @@ MAX_SUGGEST_INPUT_BYTES = 256_000
 MAX_QUERY_SCAN_FILES = 2_000
 MAX_QUERY_SCAN_BYTES_PER_FILE = 200_000
 MAX_REPO_MAP_FILES = 1_000
+MAX_REPO_MAP_SCAN_FILES = 160
 MAX_REPO_MAP_BYTES_PER_FILE = 120_000
 MAX_REPO_MAP_TREE_ENTRIES = 30
 MAX_REPO_MAP_SIGNATURE_ENTRIES = 40
 MAX_REPO_MAP_GRAPH_RANK_ENTRIES = 30
 MAX_REPO_MAP_RETRIEVAL_HINTS = 30
 MAX_REPO_MAP_SECRET_RISK_FILES = 20
+MAX_ADAPTIVE_K_SCORE_SAMPLES = 200
+MAX_SYMBOL_MEMORY_ITEMS = 12
+MAX_SYMBOL_MEMORY_GRAPH_ITEMS = 12
 PACK_DIR = ".context-guard/packs"
 REDACTED_PATH_COMPONENT = "[REDACTED-PATH-COMPONENT]"
+ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
+    "tmp": Path("/private/tmp"),
+    "var": Path("/private/var"),
+}
 CONTROL_CHAR_RE = re.compile(r"[\x00-\x1f\x7f-\x9f]")
 SECRET_CONTENT_RE = re.compile(
     r"(?is)("
@@ -235,6 +245,30 @@ def sanitize_text(text: str, *, show_paths: bool = False) -> tuple[str, int]:
     return "".join(out), redacted
 
 
+def sanitize_source_lines(handle: Any, requested: LineRange | None) -> tuple[list[str], int, int]:
+    """Sanitize a source stream while retaining only the requested line window.
+
+    Explicit line-window retrieval still scans the complete file so global
+    redaction counts and total line counts stay compatible with previous
+    outputs, but it no longer materializes a sanitized all-lines list before
+    slicing.
+    """
+    sanitizer = load_line_sanitizer()
+    selected: list[str] = []
+    redacted = 0
+    total_lines = 0
+    collect_all = requested is None
+    start = requested.start if requested is not None else 1
+    end = requested.end if requested is not None else 0
+    for total_lines, raw_line in enumerate(handle, start=1):
+        sanitized, did_redact = sanitizer.sanitize(raw_line)  # type: ignore[attr-defined]
+        if did_redact:
+            redacted += 1
+        if collect_all or start <= total_lines <= end:
+            selected.append(sanitized)
+    return selected, total_lines, redacted
+
+
 def byte_len(text: str) -> int:
     return len(text.encode("utf-8", errors="replace"))
 
@@ -342,13 +376,150 @@ def cap_label(value: object, default: str | None = None, limit: int = MAX_LABEL_
     return text
 
 
-def read_manifest(path: Path) -> list[SourceSpec]:
+def normalized_link_target(anchor: Path, raw_target: str) -> Path:
+    target = Path(raw_target)
+    if not target.is_absolute():
+        target = anchor / target
+    return Path(os.path.normpath(str(target)))
+
+
+def normalize_allowed_first_absolute_symlink(path: Path) -> Path:
+    """Normalize common macOS absolute path aliases before no-follow traversal."""
+
+    if not path.is_absolute() or len(path.parts) < 2:
+        return path
+    first = path.parts[1]
+    expected = ALLOWED_FIRST_ABSOLUTE_SYMLINKS.get(first)
+    if expected is None:
+        return path
+    link = Path(path.anchor) / first
+    try:
+        if not stat.S_ISLNK(os.lstat(link).st_mode):
+            return path
+        if normalized_link_target(Path(path.anchor), os.readlink(link)) != expected:
+            return path
+    except OSError:
+        return path
+    return expected.joinpath(*path.parts[2:])
+
+
+def manifest_safe_read_supported() -> bool:
+    return hasattr(os, "O_NOFOLLOW") and os.open in getattr(os, "supports_dir_fd", set())
+
+
+def manifest_directory_open_flags(*, follow_final: bool = False) -> int:
+    flags = os.O_RDONLY
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if not follow_final:
+        flags |= os.O_NOFOLLOW
+    return flags
+
+
+def manifest_file_open_flags() -> int:
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    for name in ("O_CLOEXEC", "O_NONBLOCK", "O_NOCTTY"):
+        flags |= getattr(os, name, 0)
+    return flags
+
+
+def manifest_leaf_name(path: Path) -> str:
+    name = path.name
+    if name in {"", ".", ".."}:
+        raise PackError("manifest path must name a regular file")
+    return name
+
+
+def open_manifest_parent_no_follow(path: Path) -> int:
+    if not manifest_safe_read_supported():
+        raise PackError("safe manifest reads require O_NOFOLLOW and dir_fd support")
+    path = path.expanduser()
+    if any(part == ".." for part in path.parts):
+        raise PackError("manifest path must not contain parent traversal")
+    if path.is_absolute():
+        path = normalize_allowed_first_absolute_symlink(Path(os.path.normpath(str(path))))
+        current_fd = os.open(path.anchor or os.sep, manifest_directory_open_flags(follow_final=True))
+        parts = path.parts[1:-1]
+    else:
+        path = Path(os.path.normpath(str(path)))
+        current_fd = os.open(".", manifest_directory_open_flags())
+        parts = path.parts[:-1]
+    try:
+        for part in parts:
+            if part in {"", "."}:
+                continue
+            if part == "..":
+                raise PackError("manifest path must not contain parent traversal")
+            next_fd = -1
+            try:
+                next_fd = os.open(part, manifest_directory_open_flags(), dir_fd=current_fd)
+                if not stat.S_ISDIR(os.fstat(next_fd).st_mode):
+                    raise PackError("manifest path must not traverse non-directory components")
+            except (OSError, PackError):
+                if next_fd >= 0:
+                    try:
+                        os.close(next_fd)
+                    except OSError:
+                        pass
+                raise
+            os.close(current_fd)
+            current_fd = next_fd
+        owned_fd = current_fd
+        current_fd = -1
+        return owned_fd
+    finally:
+        if current_fd >= 0:
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+
+
+def read_manifest_bytes_no_follow(path: Path) -> bytes:
+    parent_fd = -1
+    fd = -1
     try:
-        raw = path.read_bytes()
+        leaf = manifest_leaf_name(path.expanduser())
+        parent_fd = open_manifest_parent_no_follow(path)
+        fd = os.open(leaf, manifest_file_open_flags(), dir_fd=parent_fd)
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode):
+            raise PackError("manifest must be a regular file")
+        if st.st_size > MAX_MANIFEST_BYTES:
+            raise PackError(f"manifest exceeds trusted size cap: {st.st_size} > {MAX_MANIFEST_BYTES}")
+        chunks: list[bytes] = []
+        remaining = MAX_MANIFEST_BYTES + 1
+        while remaining > 0:
+            chunk = os.read(fd, min(64 * 1024, remaining))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        raw = b"".join(chunks)
+        if len(raw) > MAX_MANIFEST_BYTES:
+            raise PackError(f"manifest exceeds trusted size cap: {len(raw)} > {MAX_MANIFEST_BYTES}")
+        return raw
+    except PackError:
+        raise
     except OSError as exc:
         raise PackError(f"could not read manifest: {exc.strerror or exc.__class__.__name__}") from exc
-    if len(raw) > MAX_MANIFEST_BYTES:
-        raise PackError(f"manifest exceeds trusted size cap: {len(raw)} > {MAX_MANIFEST_BYTES}")
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        if parent_fd >= 0:
+            try:
+                os.close(parent_fd)
+            except OSError:
+                pass
+
+
+def read_manifest(path: Path) -> list[SourceSpec]:
+    raw = read_manifest_bytes_no_follow(path)
     try:
         data = json.loads(raw.decode("utf-8"))
     except (UnicodeDecodeError, json.JSONDecodeError) as exc:
@@ -582,19 +753,15 @@ def resolve_source(root: Path, spec: SourceSpec) -> tuple[ResolvedSource | None,
         return None, omission(spec, reason, path=display, redacted_path=redacted_path)
     try:
         with handle:
-            raw_text = handle.read()
+            requested = spec.lines
+            selected, total_lines, redacted_lines = sanitize_source_lines(handle, requested)
     except OSError:
         return None, omission(spec, "unsafe_path", path=display, redacted_path=redacted_path)
-    sanitized, redacted_lines = sanitize_text(raw_text)
-    all_lines = sanitized.splitlines(True)
-    if not all_lines:
+    if total_lines <= 0:
         return None, omission(spec, "empty_source", path=display, redacted_path=redacted_path)
-    total_lines = len(all_lines)
-    requested = spec.lines or LineRange(1, total_lines)
+    requested = requested or LineRange(1, total_lines)
     if requested.start > total_lines:
         return None, omission(spec, "empty_source", path=display, redacted_path=redacted_path)
-    end = min(requested.end, total_lines)
-    selected = all_lines[requested.start - 1:end]
     if not selected:
         return None, omission(spec, "empty_source", path=display, redacted_path=redacted_path)
     return ResolvedSource(
@@ -645,7 +812,11 @@ def retrieval_for(root_arg: str, display_path: str, lines: LineRange, *, redacte
     return retrieval_cli(safe_root, display_path, lines), None
 
 
-def render_block(source: ResolvedSource, lines: list[str], *, root_arg: str, status: str, included: LineRange) -> str:
+BLOCK_OPEN = "\n\n```text\n"
+BLOCK_CLOSE = "```\n\n"
+
+
+def render_block_header(source: ResolvedSource, *, root_arg: str, status: str, included: LineRange) -> str:
     title = source.spec.label or source.display_path
     requested = source.requested_lines or LineRange(1, source.total_lines)
     retrieval, retrieval_omitted_reason = retrieval_for(root_arg, source.display_path, included, redacted_path=source.redacted_path)
@@ -661,7 +832,11 @@ def render_block(source: ResolvedSource, lines: list[str], *, root_arg: str, sta
         header.append(f"Retrieval: `{retrieval}`")
     elif retrieval_omitted_reason:
         header.append(f"Retrieval omitted: {retrieval_omitted_reason}")
-    return "\n".join(header) + "\n\n```text\n" + "".join(lines) + ("" if not lines or lines[-1].endswith("\n") else "\n") + "```\n\n"
+    return "\n".join(header)
+
+
+def render_block(source: ResolvedSource, lines: list[str], *, root_arg: str, status: str, included: LineRange) -> str:
+    return render_block_header(source, root_arg=root_arg, status=status, included=included) + BLOCK_OPEN + "".join(lines) + ("" if not lines or lines[-1].endswith("\n") else "\n") + BLOCK_CLOSE
 
 
 def source_metadata(source: ResolvedSource, *, status: str, lines: list[str], included: LineRange, root_arg: str) -> dict[str, Any]:
@@ -701,21 +876,63 @@ def budget_omission(source: ResolvedSource, *, root_arg: str) -> dict[str, Any]:
     return item
 
 
-def fit_partial_lines(source: ResolvedSource, remaining: int, *, root_arg: str) -> tuple[list[str], str | None, LineRange | None]:
+def included_range_for_line_count(source: ResolvedSource, line_count: int) -> LineRange:
+    start = source.requested_lines.start if source.requested_lines else 1
+    return LineRange(start, start + line_count - 1)
+
+
+def line_byte_prefixes(lines: list[str]) -> list[int]:
+    prefixes = [0]
+    total = 0
+    for line in lines:
+        total += byte_len(line)
+        prefixes.append(total)
+    return prefixes
+
+
+def render_block_byte_len(
+    source: ResolvedSource,
+    line_count: int,
+    line_prefixes: list[int],
+    *,
+    root_arg: str,
+    status: str,
+    included: LineRange,
+) -> int:
+    body_bytes = line_prefixes[line_count]
+    if line_count > 0 and not source.selected_lines[line_count - 1].endswith("\n"):
+        body_bytes += 1
+    return byte_len(render_block_header(source, root_arg=root_arg, status=status, included=included)) + byte_len(BLOCK_OPEN) + body_bytes + byte_len(BLOCK_CLOSE)
+
+
+def fit_partial_lines(
+    source: ResolvedSource,
+    remaining: int,
+    *,
+    root_arg: str,
+    line_prefixes: list[int] | None = None,
+) -> tuple[list[str], str | None, LineRange | None]:
     if remaining <= 0:
         return [], None, None
-    picked: list[str] = []
-    for line in source.selected_lines:
-        candidate = picked + [line]
-        included = LineRange(source.requested_lines.start if source.requested_lines else 1, (source.requested_lines.start if source.requested_lines else 1) + len(candidate) - 1)
-        block = render_block(source, candidate, root_arg=root_arg, status="partial", included=included)
-        if byte_len(block) <= remaining:
-            picked = candidate
+    if not source.selected_lines:
+        return [], None, None
+    prefixes = line_prefixes if line_prefixes is not None else line_byte_prefixes(source.selected_lines)
+    best = 0
+    low = 1
+    high = len(source.selected_lines)
+    while low <= high:
+        mid = (low + high) // 2
+        included = included_range_for_line_count(source, mid)
+        block_bytes = render_block_byte_len(source, mid, prefixes, root_arg=root_arg, status="partial", included=included)
+        if block_bytes <= remaining:
+            best = mid
+            low = mid + 1
         else:
-            break
-    if not picked:
+            high = mid - 1
+    if best <= 0:
         return [], None, None
-    included = LineRange(source.requested_lines.start if source.requested_lines else 1, (source.requested_lines.start if source.requested_lines else 1) + len(picked) - 1)
+    picked = source.selected_lines[:best]
+    included = included_range_for_line_count(source, best)
     return picked, render_block(source, picked, root_arg=root_arg, status="partial", included=included), included
 
 
@@ -988,17 +1205,17 @@ def build_pack(root: Path, specs: list[SourceSpec], *, budget_bytes: int, root_a
         parts.append(header)
         current_pack_bytes += header_bytes
     for source in resolved:
-        start_line = source.requested_lines.start if source.requested_lines else 1
-        included_range = LineRange(start_line, start_line + len(source.selected_lines) - 1)
-        full_block = render_block(source, source.selected_lines, root_arg=root_arg, status="included", included=included_range)
-        full_block_bytes = byte_len(full_block)
+        line_prefixes = line_byte_prefixes(source.selected_lines)
+        included_range = included_range_for_line_count(source, len(source.selected_lines))
+        full_block_bytes = render_block_byte_len(source, len(source.selected_lines), line_prefixes, root_arg=root_arg, status="included", included=included_range)
         remaining = budget_bytes - current_pack_bytes
         if full_block_bytes <= remaining:
+            full_block = render_block(source, source.selected_lines, root_arg=root_arg, status="included", included=included_range)
             parts.append(full_block)
             current_pack_bytes += full_block_bytes
             included.append(source_metadata(source, status="included", lines=source.selected_lines, included=included_range, root_arg=root_arg))
             continue
-        partial_lines, partial_block, partial_range = fit_partial_lines(source, remaining, root_arg=root_arg)
+        partial_lines, partial_block, partial_range = fit_partial_lines(source, remaining, root_arg=root_arg, line_prefixes=line_prefixes)
         if partial_block is not None and partial_range is not None:
             parts.append(partial_block)
             current_pack_bytes += byte_len(partial_block)
@@ -1358,7 +1575,8 @@ def source_selected_range(source: ResolvedSource) -> LineRange:
 
 def resolved_block_bytes(source: ResolvedSource, *, root_arg: str) -> int:
     included = source_selected_range(source)
-    return byte_len(render_block(source, source.selected_lines, root_arg=root_arg, status="included", included=included))
+    line_prefixes = line_byte_prefixes(source.selected_lines)
+    return render_block_byte_len(source, len(source.selected_lines), line_prefixes, root_arg=root_arg, status="included", included=included)
 
 
 def manifest_source_for_candidate(source: ResolvedSource, *, priority: int, label: str | None) -> dict[str, Any]:
@@ -1638,6 +1856,136 @@ def suggest_build_hint(root_arg: str, manifest_path: str | None, budget: int) ->
     return f"cd {shlex.quote(safe_root)} && {command}", None
 
 
+def percentile_int(values: list[int], numerator: int, denominator: int) -> int:
+    if not values:
+        return 0
+    if denominator <= 0:
+        return values[0]
+    index = min(len(values) - 1, max(0, (len(values) - 1) * numerator // denominator))
+    return values[index]
+
+
+def score_gap_advice(scores: list[int], requested_top: int) -> tuple[int, dict[str, Any], list[str]]:
+    if not scores:
+        return 0, {"after_rank": 0, "delta": 0, "ratio": 0.0}, ["no_candidates"]
+    if len(scores) == 1:
+        return 1, {"after_rank": 1, "delta": 0, "ratio": 0.0}, ["single_candidate"]
+    gaps = [max(0, scores[index] - scores[index + 1]) for index in range(len(scores) - 1)]
+    max_gap = max(gaps)
+    gap_index = gaps.index(max_gap)
+    top_score = max(1, scores[0])
+    ratio = round(max_gap / top_score, 4)
+    if max_gap >= max(250, top_score // 5):
+        elbow_k = gap_index + 1
+        reasons = ["score_elbow"] if elbow_k <= requested_top else ["score_elbow_after_requested_top"]
+    else:
+        elbow_k = min(MAX_SUGGEST_TOP, len(scores))
+        reasons = ["no_strong_score_elbow"]
+    return max(1, elbow_k), {"after_rank": gap_index + 1, "delta": max_gap, "ratio": ratio}, reasons
+
+
+def build_adaptive_k_advisory(
+    *,
+    candidates: list[SuggestCandidate],
+    selected: list[dict[str, Any]],
+    omitted: list[dict[str, Any]],
+    requested_top: int,
+    budget_bytes: int,
+    estimated_pack_bytes: int,
+) -> dict[str, Any]:
+    sampled_candidates = candidates[:MAX_ADAPTIVE_K_SCORE_SAMPLES]
+    scores = [max(0, int(candidate.score)) for candidate in sampled_candidates]
+    score_elbow_k, max_gap_details, reason_codes = score_gap_advice(scores, requested_top)
+    selected_count = len(selected)
+    selected_scores = [max(0, int(item.get("score", item.get("priority", 0)) or 0)) for item in selected]
+    selected_score_mass = sum(selected_scores)
+    analyzed_score_mass = sum(scores)
+    budget_omitted_count = sum(1 for item in omitted if item.get("reason") == "budget_exhausted")
+    budget_limited = bool(budget_omitted_count or estimated_pack_bytes > budget_bytes)
+    remaining_bytes = budget_bytes - estimated_pack_bytes
+    average_selected_bytes = int(estimated_pack_bytes / selected_count) if selected_count else 0
+    if budget_limited:
+        reason_codes.append("budget_limited")
+    if len(candidates) > len(sampled_candidates):
+        reason_codes.append("candidate_sample_capped")
+    if selected_count < min(requested_top, len(candidates)):
+        reason_codes.append("selected_below_requested_top")
+    if selected_count == 0:
+        budget_fit_k = 0
+        if candidates:
+            reason_codes.append("no_budget_fit" if budget_limited else "no_selected_sources")
+    elif budget_limited:
+        budget_fit_k = selected_count
+    else:
+        additional_by_budget = max(0, remaining_bytes // max(1, average_selected_bytes))
+        budget_fit_k = min(MAX_SUGGEST_TOP, len(candidates), selected_count + additional_by_budget)
+        if budget_fit_k > requested_top:
+            reason_codes.append("budget_headroom_expand")
+    if not candidates:
+        recommended_k = 0
+    else:
+        recommended_k = min(
+            max(0, score_elbow_k),
+            max(0, budget_fit_k),
+            len(candidates),
+            MAX_SUGGEST_TOP,
+        )
+    score_values_asc = sorted(scores)
+    top_score = score_values_asc[-1] if score_values_asc else 0
+    return {
+        "schema_version": ADAPTIVE_K_SCHEMA_VERSION,
+        "mode": "advisory",
+        "requested_top": requested_top,
+        "recommended_k": recommended_k,
+        "recommendation": {
+            "apply": False,
+            "reason_codes": sorted(set(reason_codes)),
+            "next_step": "rerun with --top recommended_k if you accept this local proxy advisory",
+        },
+        "score_distribution": {
+            "candidate_count": len(candidates),
+            "analyzed_candidate_count": len(sampled_candidates),
+            "sample_capped": len(candidates) > len(sampled_candidates),
+            "top_score": top_score,
+            "p50_score": percentile_int(score_values_asc, 1, 2),
+            "p90_score": percentile_int(score_values_asc, 9, 10),
+            "min_score": score_values_asc[0] if score_values_asc else 0,
+            "max_gap_details": max_gap_details,
+            "score_elbow_k": score_elbow_k,
+        },
+        "budget_fit": {
+            "budget_bytes": budget_bytes,
+            "estimated_pack_bytes": estimated_pack_bytes,
+            "remaining_bytes": remaining_bytes,
+            "selected_count": selected_count,
+            "budget_omitted_count": budget_omitted_count,
+            "budget_limited": budget_limited,
+            "average_selected_bytes": average_selected_bytes,
+            "budget_fit_k": budget_fit_k,
+        },
+        "recall_precision_proxy": {
+            "measurement": "local_score_mass_proxy",
+            "selected_score_mass": selected_score_mass,
+            "analyzed_score_mass": analyzed_score_mass,
+            "recall_proxy": round(selected_score_mass / analyzed_score_mass, 4) if analyzed_score_mass else 0.0,
+            "precision_proxy": (
+                round((selected_score_mass / max(1, selected_count)) / max(1, top_score), 4)
+                if selected_count
+                else 0.0
+            ),
+            "selected_count": selected_count,
+            "candidate_count": len(candidates),
+        },
+        "claim_boundary": {
+            "deterministic_local_only": True,
+            "no_model_network_or_embedding": True,
+            "token_counts_are_estimated_proxies": True,
+            "provider_token_or_cost_savings_claim_allowed": False,
+            "advisory_does_not_change_manifest_or_pack": True,
+        },
+    }
+
+
 def suggest_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tuple[dict[str, Any], int]:
     query_text, _query_redactions = sanitize_text(args.query or "")
     query = " ".join(query_text.split())
@@ -1713,11 +2061,19 @@ def suggest_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tupl
             })
             continue
         final_seen.add(final_identity)
-        source_bytes = resolved_block_bytes(source, root_arg=root_arg)
+        line_prefixes = line_byte_prefixes(source.selected_lines)
+        source_bytes = render_block_byte_len(
+            source,
+            len(source.selected_lines),
+            line_prefixes,
+            root_arg=root_arg,
+            status="included",
+            included=source_selected_range(source),
+        )
         remaining = budget - current_bytes
         if source_bytes > remaining:
             if not selected and remaining > 0:
-                partial_lines, _partial_block, partial_range = fit_partial_lines(source, remaining, root_arg=root_arg)
+                partial_lines, _partial_block, partial_range = fit_partial_lines(source, remaining, root_arg=root_arg, line_prefixes=line_prefixes)
                 if partial_range is not None and partial_lines:
                     partial_spec = SourceSpec(
                         path=candidate.path,
@@ -1734,7 +2090,15 @@ def suggest_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tupl
                         omitted.append(omitted_item)
                         continue
                     assert source is not None
-                    source_bytes = resolved_block_bytes(source, root_arg=root_arg)
+                    partial_prefixes = line_byte_prefixes(source.selected_lines)
+                    source_bytes = render_block_byte_len(
+                        source,
+                        len(source.selected_lines),
+                        partial_prefixes,
+                        root_arg=root_arg,
+                        status="included",
+                        included=source_selected_range(source),
+                    )
                 else:
                     omitted.append({"path": source.display_path, "status": "omitted", "reason": "budget_exhausted", "priority": candidate.score})
                     continue
@@ -1780,6 +2144,15 @@ def suggest_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tupl
     }
     if build_hint_omitted_reason:
         payload["build_hint_omitted_reason"] = build_hint_omitted_reason
+    if getattr(args, "adaptive_k", False):
+        payload["adaptive_k"] = build_adaptive_k_advisory(
+            candidates=candidates,
+            selected=selected,
+            omitted=omitted,
+            requested_top=top,
+            budget_bytes=budget,
+            estimated_pack_bytes=estimated_pack_bytes,
+        )
     return payload, 0
 
 
@@ -1893,20 +2266,53 @@ def read_repo_map_text(root: Path, rel_path: str) -> tuple[dict[str, Any] | None
     }, None
 
 
-def repo_map_records(root: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]:
+def repo_map_path_scan_priority(rel_path: str, *, seed_paths: set[str], query_terms: set[str], input_index: int) -> tuple[int, int, str]:
+    rel, reason = lexical_rel(rel_path)
+    display = repo_map_safe_raw_path_label(rel_path)
+    redacted = False
+    if rel is not None and not reason:
+        display, redacted = repo_map_display_rel_path(rel.as_posix())
+    score = 0
+    if not redacted and display in seed_paths:
+        score += 1_000_000
+    if is_repo_map_text_path(display):
+        score += 10_000
+    score += suggest_score_path(display, query_terms)
+    if Path(display).name.lower() in {"readme", "readme.md", "readme.mdx"}:
+        score += 250
+    return (-score, input_index, display)
+
+
+def repo_map_scan_paths(paths: list[str], *, seed_paths: set[str], query_terms: set[str]) -> list[str]:
+    ranked = sorted(
+        enumerate(paths[:MAX_REPO_MAP_FILES]),
+        key=lambda item: repo_map_path_scan_priority(item[1], seed_paths=seed_paths, query_terms=query_terms, input_index=item[0]),
+    )
+    return [path for _index, path in ranked[:MAX_REPO_MAP_SCAN_FILES]]
+
+
+def repo_map_records(root: Path, *, seed_paths: set[str], query_terms: set[str]) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]:
     paths = git_ls_files(root)
+    candidate_paths = paths[:MAX_REPO_MAP_FILES]
     path_cap_reached = len(paths) > MAX_REPO_MAP_FILES
+    scan_paths = repo_map_scan_paths(candidate_paths, seed_paths=seed_paths, query_terms=query_terms)
+    scan_cap_reached = len(candidate_paths) > len(scan_paths)
     records: list[dict[str, Any]] = []
     omitted: list[dict[str, Any]] = []
-    for rel_path in paths[:MAX_REPO_MAP_FILES]:
+    for rel_path in scan_paths:
         record, omission_item = read_repo_map_text(root, rel_path)
         if record is not None:
             records.append(record)
         elif omission_item is not None and omission_item.get("reason") != "unsupported_file_type":
             omitted.append({key: value for key, value in omission_item.items() if value is not None})
     caps = {
-        "max_files": MAX_REPO_MAP_FILES,
-        "files_capped": path_cap_reached,
+        "max_files": MAX_REPO_MAP_SCAN_FILES,
+        "files_capped": path_cap_reached or scan_cap_reached,
+        "max_candidate_files": MAX_REPO_MAP_FILES,
+        "candidate_files": len(candidate_paths),
+        "candidate_files_capped": path_cap_reached,
+        "scan_files": len(scan_paths),
+        "scan_files_capped": scan_cap_reached,
         "max_bytes_per_file": MAX_REPO_MAP_BYTES_PER_FILE,
         "bytes_per_file_capped_count": sum(1 for item in records if item.get("bytes_capped")),
         "max_tree_entries": MAX_REPO_MAP_TREE_ENTRIES,
@@ -2256,18 +2662,19 @@ def build_repo_map_payload(
     *,
     root_arg: str,
 ) -> dict[str, Any]:
-    records, omitted, caps = repo_map_records(root)
+    query_terms = suggest_tokens(str(suggest_payload.get("query", "")))
+    seed_paths = repo_map_seed_paths(args, suggest_payload, build_payload)
+    records, omitted, caps = repo_map_records(root, seed_paths=seed_paths, query_terms=query_terms)
     record_by_path = {str(record["path"]): record for record in records}
     signatures = extract_signatures(records)
     secret_scan = build_secret_scan(records)
     edges = collect_import_edges(records)
-    query_terms = suggest_tokens(str(suggest_payload.get("query", "")))
     graph_rank = build_graph_rank(
         records,
         signatures,
         edges,
         query_terms=query_terms,
-        seed_paths=repo_map_seed_paths(args, suggest_payload, build_payload),
+        seed_paths=seed_paths,
         secret_scan=secret_scan,
     )
     retrieval = repo_map_retrieval(record_by_path, signatures, graph_rank, root_arg=root_arg)
@@ -2312,6 +2719,90 @@ def build_repo_map_payload(
     }
 
 
+def line_identity_from_dict(value: object) -> str:
+    if not isinstance(value, dict):
+        return "all"
+    return f"{value.get('start')}:{value.get('end')}"
+
+
+def build_symbol_memory_payload(repo_map: dict[str, Any]) -> dict[str, Any]:
+    retrieval_by_path_lines: dict[tuple[str, str], dict[str, Any]] = {}
+    for item in repo_map.get("retrieval", []):
+        if not isinstance(item, dict):
+            continue
+        path = str(item.get("path", ""))
+        retrieval_by_path_lines[(path, line_identity_from_dict(item.get("lines")))] = item
+
+    symbols: list[dict[str, Any]] = []
+    for signature in repo_map.get("signature_index", []):
+        if not isinstance(signature, dict):
+            continue
+        path = str(signature.get("path", ""))
+        lines = copy.deepcopy(signature.get("lines"))
+        retrieval = retrieval_by_path_lines.get((path, line_identity_from_dict(lines)))
+        symbol: dict[str, Any] = {
+            "path": path,
+            "kind": signature.get("kind"),
+            "name": signature.get("name"),
+            "signature": signature.get("signature"),
+            "line": signature.get("line"),
+            "lines": lines,
+            "source": "repo_map.signature_index",
+            "exact_source_verification_required": True,
+        }
+        if isinstance(retrieval, dict):
+            for key in ("slice_cli", "symbol_cli", "retrieval_omitted_reason"):
+                if retrieval.get(key):
+                    symbol[key] = retrieval[key]
+        symbols.append({key: value for key, value in symbol.items() if value is not None})
+        if len(symbols) >= MAX_SYMBOL_MEMORY_ITEMS:
+            break
+
+    graph_context: list[dict[str, Any]] = []
+    for item in repo_map.get("graph_rank", []):
+        if not isinstance(item, dict):
+            continue
+        graph_context.append({
+            "path": item.get("path"),
+            "score": item.get("score"),
+            "components": copy.deepcopy(item.get("components", {})),
+            "line_count": item.get("line_count"),
+            "exact_source_verification_required": True,
+        })
+        if len(graph_context) >= MAX_SYMBOL_MEMORY_GRAPH_ITEMS:
+            break
+
+    summary = repo_map.get("summary", {}) if isinstance(repo_map.get("summary"), dict) else {}
+    retrieval = repo_map.get("retrieval", []) if isinstance(repo_map.get("retrieval"), list) else []
+    return {
+        "schema_version": SYMBOL_MEMORY_SCHEMA_VERSION,
+        "mode": "advisory",
+        "source": "contextguard.pack-repo-map.v1",
+        "summary": {
+            "symbols": len(symbols),
+            "graph_context": len(graph_context),
+            "files_scanned": int(summary.get("files_scanned", 0) or 0),
+            "graph_edges": int(summary.get("graph_edges", 0) or 0),
+            "retrieval_hints": len(retrieval),
+        },
+        "symbols": symbols,
+        "graph_context": graph_context,
+        "source_verification": {
+            "requires_exact_source_before_edits": True,
+            "verified_by": ["slice_cli", "symbol_cli"],
+            "retrieval_hint_count": len(retrieval),
+            "missing_retrieval_hint_count": max(0, len(symbols) - sum(1 for item in symbols if item.get("slice_cli") or item.get("symbol_cli"))),
+        },
+        "claim_boundary": {
+            "deterministic_local_only": True,
+            "no_network_model_embedding_lsp_or_tree_sitter_dependency": True,
+            "advisory_does_not_change_manifest_pack_or_receipt": True,
+            "graph_rank_is_explain_only": True,
+            "provider_token_or_cost_savings_claim_allowed": False,
+        },
+    }
+
+
 def build_auto_explain_payload(
     args: argparse.Namespace,
     suggest_payload: dict[str, Any],
@@ -2320,6 +2811,7 @@ def build_auto_explain_payload(
     *,
     root: Path | None = None,
     root_arg: str = ".",
+    repo_map_payload: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     build_sources = [
         item
@@ -2447,7 +2939,9 @@ def build_auto_explain_payload(
             "raw_test_output_embedded": False,
         },
     }
-    if root is not None:
+    if repo_map_payload is not None:
+        explain["repo_map"] = copy.deepcopy(repo_map_payload)
+    elif root is not None:
         explain["repo_map"] = build_repo_map_payload(root, args, suggest_payload, build_payload, root_arg=root_arg)
     return explain
 
@@ -2534,11 +3028,70 @@ def auto_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tuple[d
     }
     if build_hint_omitted_reason:
         payload["build_hint_omitted_reason"] = build_hint_omitted_reason
+    if getattr(args, "adaptive_k", False) and isinstance(suggest_payload.get("adaptive_k"), dict):
+        payload["adaptive_k"] = copy.deepcopy(suggest_payload["adaptive_k"])
+    repo_map_payload: dict[str, Any] | None = None
+    if getattr(args, "symbol_memory", False) or args.explain:
+        repo_map_payload = build_repo_map_payload(root, args, suggest_payload, build_payload, root_arg=root_arg)
+    if getattr(args, "symbol_memory", False) and isinstance(repo_map_payload, dict):
+        payload["symbol_memory"] = build_symbol_memory_payload(repo_map_payload)
     if args.explain:
-        payload["explain"] = build_auto_explain_payload(args, suggest_payload, build_payload, payload, root=root, root_arg=root_arg)
+        payload["explain"] = build_auto_explain_payload(
+            args,
+            suggest_payload,
+            build_payload,
+            payload,
+            root=root,
+            root_arg=root_arg,
+            repo_map_payload=repo_map_payload,
+        )
     return payload, rc
 
 
+def print_adaptive_k_text(payload: dict[str, Any]) -> None:
+    adaptive = payload.get("adaptive_k")
+    if not isinstance(adaptive, dict):
+        return
+    recommendation = (
+        adaptive.get("recommendation", {})
+        if isinstance(adaptive.get("recommendation"), dict)
+        else {}
+    )
+    score_distribution = (
+        adaptive.get("score_distribution", {})
+        if isinstance(adaptive.get("score_distribution"), dict)
+        else {}
+    )
+    budget_fit = adaptive.get("budget_fit", {}) if isinstance(adaptive.get("budget_fit"), dict) else {}
+    reason_codes = recommendation.get("reason_codes", [])
+    if isinstance(reason_codes, list):
+        reason_text = ",".join(str(item) for item in reason_codes[:5])
+    else:
+        reason_text = str(reason_codes)
+    print(
+        "adaptive-k: "
+        f"recommended={adaptive.get('recommended_k', 0)}/{adaptive.get('requested_top', 0)} "
+        f"candidates={score_distribution.get('candidate_count', 0)} "
+        f"budget_limited={budget_fit.get('budget_limited', False)} "
+        f"apply=false reasons={reason_text or 'none'}"
+    )
+
+
+def print_symbol_memory_text(payload: dict[str, Any]) -> None:
+    symbol_memory = payload.get("symbol_memory")
+    if not isinstance(symbol_memory, dict):
+        return
+    summary = symbol_memory.get("summary", {}) if isinstance(symbol_memory.get("summary"), dict) else {}
+    verification = symbol_memory.get("source_verification", {}) if isinstance(symbol_memory.get("source_verification"), dict) else {}
+    print(
+        "symbol-memory: "
+        f"symbols={summary.get('symbols', 0)} "
+        f"graph_context={summary.get('graph_context', 0)} "
+        f"retrieval_hints={summary.get('retrieval_hints', 0)} "
+        f"verify_before_edits={str(verification.get('requires_exact_source_before_edits', True)).lower()}"
+    )
+
+
 def print_suggest_text(payload: dict[str, Any]) -> None:
     print(
         f"context-guard-pack suggest: {len(payload['sources'])} source(s), "
@@ -2554,6 +3107,7 @@ def print_suggest_text(payload: dict[str, Any]) -> None:
         print(f"build: {payload['build_hint']}")
     elif payload.get("build_hint_omitted_reason"):
         print(f"build hint omitted: {payload['build_hint_omitted_reason']}")
+    print_adaptive_k_text(payload)
 
 
 def print_auto_text(payload: dict[str, Any]) -> None:
@@ -2598,6 +3152,8 @@ def print_auto_text(payload: dict[str, Any]) -> None:
                 reason_counts[reason] = reason_counts.get(reason, 0) + 1
             reason_text = ", ".join(f"{reason}={count}" for reason, count in sorted(reason_counts.items()))
             print(f"omitted reasons: {reason_text}")
+    print_adaptive_k_text(payload)
+    print_symbol_memory_text(payload)
     if payload.get("manifest_path"):
         print(f"manifest: {payload['manifest_path']}")
     if payload.get("pack_path"):
@@ -2633,6 +3189,7 @@ def build_parser() -> argparse.ArgumentParser:
     suggest.add_argument("--top", type=int, default=DEFAULT_SUGGEST_TOP, help="maximum suggested sources")
     suggest.add_argument("--context-lines", type=int, default=DEFAULT_SUGGEST_CONTEXT_LINES, help="line context around diff/output hits")
     suggest.add_argument("--manifest-out", help="write the suggested build manifest to this relative path under root")
+    suggest.add_argument("--adaptive-k", action="store_true", help="include local score/budget top-k advisory metadata without changing the manifest")
     suggest.add_argument("--json", action="store_true", help="emit JSON payload")
     auto = sub.add_parser("auto", help="suggest a context pack manifest and build the budgeted pack in one local step")
     auto.add_argument("--root", default=".", help="project root; must not be a symlink")
@@ -2649,6 +3206,8 @@ def build_parser() -> argparse.ArgumentParser:
     auto.add_argument("--json", action="store_true", help="emit JSON payload")
     auto.add_argument("--no-artifact", action="store_true", help="do not write .context-guard/packs receipt")
     auto.add_argument("--explain", action="store_true", help="include deterministic local selection/build explanation metadata")
+    auto.add_argument("--adaptive-k", action="store_true", help="include local score/budget top-k advisory metadata without changing the manifest or pack")
+    auto.add_argument("--symbol-memory", action="store_true", help="include repo-map derived symbol/graph advisory metadata with exact source verification hints")
     return parser