sourcecode 1.31.12__tar.gz → 1.31.13__tar.gz

{sourcecode-1.31.12 → sourcecode-1.31.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.31.12
+Version: 1.31.13
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -225,7 +225,7 @@ Description-Content-Type: text/markdown
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.31.12-blue)
+![Version](https://img.shields.io/badge/version-1.31.13-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -261,7 +261,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.12
+# sourcecode 1.31.13
 ```
 
 ---

{sourcecode-1.31.12 → sourcecode-1.31.13}/README.md

@@ -2,7 +2,7 @@
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.31.12-blue)
+![Version](https://img.shields.io/badge/version-1.31.13-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -38,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.12
+# sourcecode 1.31.13
 ```
 
 ---

{sourcecode-1.31.12 → sourcecode-1.31.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.31.12"
+version = "1.31.13"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.31.12 → sourcecode-1.31.13}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.31.12"
+__version__ = "1.31.13"

{sourcecode-1.31.12 → sourcecode-1.31.13}/src/sourcecode/cli.py

@@ -166,7 +166,7 @@ Compressed AI-ready context for Java/Spring enterprise codebases.
 # Known subcommand names — tokens matching these are routed as subcommands,
 # not consumed as a repository path.
 _SUBCOMMANDS: frozenset[str] = frozenset(
-    {"telemetry", "prepare-context", "version", "config", "analyze", "repo-ir", "mcp", "endpoints"}
+    {"telemetry", "prepare-context", "version", "config", "analyze", "repo-ir", "mcp", "endpoints", "impact"}
 )
 
 # Mutable container holding the path extracted by _preprocess_argv().
@@ -715,6 +715,35 @@ def main(
             err=True,
         )
 
+    # P0-2 FIX: --compact and --full are mutually exclusive.
+    # compact is designed to be a bounded summary; --full removes truncation limits,
+    # which contradicts compact's purpose. Use --agent --full for expanded output.
+    if compact and full:
+        typer.echo(
+            "Error: --compact and --full are mutually exclusive. "
+            "--compact produces a bounded summary; --full removes truncation limits and "
+            "is meant for --agent mode. Use --agent --full for expanded output.",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # P0-2 FIX: --full without --compact or --agent has no effect in contract/raw mode.
+    # Warn so the user knows the flag is not doing anything.
+    if full and not compact and not agent:
+        typer.echo(
+            "[warning] --full has no effect in contract/raw mode. "
+            "It only expands mybatis.dto_mappers and transactional_boundaries in "
+            "--compact or --agent mode. Add --agent to get expanded output.",
+            err=True,
+        )
+
+    # P0-2 FIX: --changed-only silently implies --compact; inform the user.
+    if changed_only and not compact and not agent:
+        typer.echo(
+            "[info] --changed-only implies --compact (bounding output to changed files).",
+            err=True,
+        )
+
     # Validate format choices
     if format not in FORMAT_CHOICES:
         typer.echo(
@@ -1629,6 +1658,9 @@ def main(
         data = agent_view(sm, full=full)
         if not no_redact:
             data = redact_dict(data)
+        # P0-1: Apply output budget — safety net for large repos.
+        from sourcecode.output_budget import trim_to_budget as _trim, BUDGET_AGENT
+        data = _trim(data, BUDGET_AGENT, label="agent")
         # FIX-P0-2: agent mode must honour --format yaml (previously always emitted JSON).
         if format == "yaml":
             from io import StringIO
@@ -1657,6 +1689,9 @@ def main(
         data = compact_view(sm, no_tree=no_tree, full=full)
         if not no_redact:
             data = redact_dict(data)
+        # P0-1: Apply output budget — safety net for large repos.
+        from sourcecode.output_budget import trim_to_budget as _trim_c, BUDGET_COMPACT
+        data = _trim_c(data, BUDGET_COMPACT, label="compact")
         if format == "yaml":
             from io import StringIO
             from ruamel.yaml import YAML as _YAML
@@ -2191,7 +2226,10 @@ def prepare_context_cmd(
                 _sys.stdout.buffer.write(_err_json.encode("utf-8"))
                 _sys.stdout.buffer.write(b"\n")
                 _sys.stdout.buffer.flush()
-            raise typer.Exit(code=1)
+            # FIX: no_diff (no PR changes) is not an error — exit 0, consistent
+            # with delta's no_changes handling. Only true errors exit non-zero.
+            _review_pr_exit = 0 if output.error_code == "no_diff" else 1
+            raise typer.Exit(code=_review_pr_exit)
         out["review_type"] = "pull_request"
         if output.ci_decision:
             out["ci_decision"] = output.ci_decision
@@ -2273,6 +2311,24 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
+    # P0-1: Apply output budget per task — safety net for large repos.
+    from sourcecode.output_budget import (
+        trim_to_budget as _pc_trim,
+        BUDGET_FIX_BUG, BUDGET_REVIEW_PR, BUDGET_ONBOARD,
+        BUDGET_EXPLAIN, BUDGET_REFACTOR, BUDGET_DELTA,
+    )
+    _pc_budgets: dict[str, int] = {
+        "fix-bug":         BUDGET_FIX_BUG,
+        "review-pr":       BUDGET_REVIEW_PR,
+        "onboard":         BUDGET_ONBOARD,
+        "explain":         BUDGET_EXPLAIN,
+        "refactor":        BUDGET_REFACTOR,
+        "delta":           BUDGET_DELTA,
+        "generate-tests":  BUDGET_EXPLAIN,
+    }
+    _pc_budget = _pc_budgets.get(task, BUDGET_EXPLAIN)
+    out = _pc_trim(out, _pc_budget, label=task)
+
     if format == "github-comment" and task == "review-pr":
         from sourcecode.pr_comment_renderer import render_github_comment
         _pc_content = render_github_comment(out)
@@ -2490,6 +2546,115 @@ def repo_ir_cmd(
             _sys.stdout.write("\n")
 
 
+# ── impact (blast-radius / change-impact analysis) ────────────────────────────
+
+@app.command("impact")
+def impact_cmd(
+    target: str = typer.Argument(
+        ...,
+        help=(
+            "Class name (simple or FQN) or file path to analyze impact for. "
+            "Examples: UserService, org.example.UserService, UserService.java"
+        ),
+    ),
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository root to analyze (default: current directory)",
+    ),
+    depth: int = typer.Option(
+        4,
+        "--depth",
+        help="BFS depth for indirect caller traversal (default: 4).",
+        min=1,
+        max=8,
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    include_tests: bool = typer.Option(
+        False,
+        "--include-tests",
+        help="Include test files in analysis (excluded by default).",
+    ),
+) -> None:
+    """Blast-radius analysis: who calls this class and what breaks if it changes?
+
+    \b
+    Builds the repository IR and propagates impact from the target symbol
+    through the reverse dependency graph. Returns:
+      - direct_callers     — classes that directly call or depend on the target
+      - indirect_callers   — transitive callers (BFS, bounded by --depth)
+      - endpoints_affected — HTTP endpoints that transitively depend on the target
+      - transactional_boundaries_touched — @Transactional classes in the call chain
+      - risk_score / risk_level — quantified change risk
+
+    \b
+    Examples:
+      sourcecode impact UserService
+      sourcecode impact org.keycloak.services.DefaultKeycloakSession /path/to/keycloak
+      sourcecode impact UserService --depth 6 --output impact.json
+    """
+    import json as _json
+    import sys as _sys
+
+    from sourcecode.repository_ir import (
+        build_repo_ir, find_java_files, compute_blast_radius,
+    )
+    from sourcecode.output_budget import trim_to_budget as _trim, BUDGET_IMPACT
+
+    root = path.resolve()
+    if not root.is_dir():
+        typer.echo(f"Error: {root} is not a directory", err=True)
+        raise typer.Exit(1)
+
+    file_list = find_java_files(root)
+    if not include_tests:
+        file_list = [f for f in file_list if "/test/" not in f and "/tests/" not in f]
+
+    if not file_list:
+        typer.echo(
+            _json.dumps(
+                {
+                    "target": target,
+                    "resolution": "not_found",
+                    "message": "No Java files found in repository.",
+                    "risk_level": "unknown",
+                },
+                indent=2,
+            )
+        )
+        return
+
+    _prog = Progress()
+    _prog.start(f"building IR ({len(file_list)} files) for impact analysis")
+    try:
+        ir = build_repo_ir(file_list, root)
+    finally:
+        _prog.finish()
+
+    result = compute_blast_radius(ir, target, max_depth=depth)
+    result = _trim(result, BUDGET_IMPACT, label="impact")
+
+    output = _json.dumps(result, indent=2, ensure_ascii=False)
+    if output_path:
+        output_path.write_text(output, encoding="utf-8")
+        typer.echo(f"Impact analysis written to {output_path}", err=True)
+    else:
+        try:
+            _sys.stdout.buffer.write(output.encode("utf-8"))
+            _sys.stdout.buffer.write(b"\n")
+            _sys.stdout.buffer.flush()
+        except AttributeError:
+            _sys.stdout.write(output + "\n")
+
+    # Non-zero exit when target not found
+    if result.get("resolution") == "not_found":
+        raise typer.Exit(code=1)
+
+
 # ── endpoints ─────────────────────────────────────────────────────────────────
 
 # _extract_java_endpoints is imported from sourcecode.repository_ir as the
@@ -2756,6 +2921,9 @@ def mcp_init(
 @mcp_app.command("status")
 def mcp_status() -> None:
     """Show MCP integration status: dependencies, config files, and connectivity."""
+    import subprocess as _sp
+    import sys as _sys
+    from sourcecode import __version__ as _cli_version
     from sourcecode.mcp.onboarding.detector import detect_clients, is_client_running
     from sourcecode.mcp.onboarding import applier
 
@@ -2764,6 +2932,10 @@ def mcp_status() -> None:
     typer.echo("MCP Status")
     typer.echo(sep)
 
+    # FIX-P0-5/P0-6: Show CLI version explicitly so drift is immediately visible.
+    typer.echo(f"CLI version   {_cli_version}   ({_sys.executable})")
+    typer.echo("")
+
     # Stage 1: Dependencies
     try:
         import mcp as _mcp_pkg  # noqa: F401
@@ -2782,8 +2954,7 @@ def mcp_status() -> None:
 
     # Stage 2: Config files — is sourcecode registered in the client's config?
     # FIX-P0-6: "configured" and "running" are distinct, independent checks.
-    # A client app may be running without sourcecode configured, or configured but not running.
-    # Display each state as a separate labelled field to prevent contradiction.
+    # Also detect external server installs (different Python/executable than CLI).
     typer.echo("Config (sourcecode registered in client config?)")
     for client in clients:
         if not client.app_installed:
@@ -2794,6 +2965,64 @@ def mcp_status() -> None:
         config = applier.read_config(client.config_path)
         if applier.is_installed(config):
             typer.echo(f"  {client.name:<20} ✓ configured   {client.config_path}")
+            # FIX-P0-5: inspect registered command for external-server drift.
+            _registered = config.get("mcpServers", {}).get("sourcecode", {})
+            _reg_cmd = _registered.get("command", "")
+            _reg_args = _registered.get("args", [])
+            # Built-in form: command=sourcecode args=[mcp, serve] (or just the binary)
+            _is_builtin = (
+                _reg_cmd == "sourcecode"
+                or (not _reg_args and _reg_cmd.endswith("/sourcecode"))
+                or (_reg_args and _reg_args[:2] == ["mcp", "serve"])
+            )
+            if _is_builtin:
+                typer.echo(f"    Server:  built-in (sourcecode mcp serve)  version={_cli_version}")
+            else:
+                # External server — different Python or custom server.py
+                typer.echo(f"    Server:  ⚠ EXTERNAL — {_reg_cmd} {' '.join(_reg_args)}")
+                # Try to get the external server's sourcecode version by finding the
+                # sourcecode binary relative to the registered Python executable,
+                # or falling back to probing the Python for the installed package.
+                _ext_ver: str = "unknown"
+                try:
+                    import os as _os
+                    # Strategy 1: look for sourcecode binary next to registered Python
+                    _reg_bin_dir = _os.path.dirname(_reg_cmd)
+                    _sc_sibling = _os.path.join(_reg_bin_dir, "sourcecode")
+                    if _os.path.isfile(_sc_sibling):
+                        _ver_r = _sp.run(
+                            [_sc_sibling, "--version"],
+                            capture_output=True, text=True, timeout=5,
+                        )
+                        if _ver_r.returncode == 0 and _ver_r.stdout.strip():
+                            # "sourcecode X.Y.Z" → extract version
+                            _ext_ver = _ver_r.stdout.strip().split()[-1]
+                    # Strategy 2: import via registered Python
+                    if _ext_ver == "unknown":
+                        _ver_r2 = _sp.run(
+                            [_reg_cmd, "-c",
+                             "import sourcecode; print(sourcecode.__version__)"],
+                            capture_output=True, text=True, timeout=5,
+                        )
+                        if _ver_r2.returncode == 0 and _ver_r2.stdout.strip():
+                            _ext_ver = _ver_r2.stdout.strip()
+                except Exception:
+                    pass
+                if _ext_ver != "unknown" and _ext_ver != _cli_version:
+                    typer.echo(
+                        f"    ⚠ VERSION DRIFT: external server version={_ext_ver}, "
+                        f"CLI version={_cli_version}"
+                    )
+                    typer.echo(
+                        "    To fix: sourcecode mcp init  (re-register using CLI built-in server)"
+                    )
+                elif _ext_ver != "unknown":
+                    typer.echo(f"    External server version={_ext_ver}  (matches CLI ✓)")
+                else:
+                    typer.echo(
+                        f"    ⚠ Cannot verify external server version (CLI={_cli_version}). "
+                        "Re-run: sourcecode mcp init to switch to built-in server."
+                    )
         else:
             typer.echo(f"  {client.name:<20} ✗ not configured  (app found, but sourcecode entry missing)")
             typer.echo(f"    Fix: sourcecode mcp init --target {client.slug}")

{sourcecode-1.31.12 → sourcecode-1.31.13}/src/sourcecode/mcp/server.py

@@ -93,8 +93,14 @@ def get_endpoints(repo_path: str = ".") -> dict:
 
     Maps to: sourcecode endpoints <repo_path>
     Returns: endpoints list with method, path, controller, handler fields;
-             total (int) and undocumented (int) counts.
+             security dict when authorization annotations are present
+             (policy: roles_allowed|permit_all|deny_all|authenticated|...);
+             total (int) and no_security_signal (int) counts.
+             no_security_signal counts endpoints with no recognized auth annotation —
+             repos using framework-level auth (e.g. Keycloak) may show high counts.
     Supports Spring MVC (@GetMapping etc.) and JAX-RS (@GET/@POST etc.).
+    Security annotations detected: @RolesAllowed, @PermitAll, @DenyAll,
+    @Authenticated, @PreAuthorize, @Secured, @SecurityRequirement, @M3FiltroSeguridad.
     repo_path: absolute path to the repository (default: current working directory).
     """
     if not isinstance(repo_path, str):
@@ -135,11 +141,17 @@ def get_delta(repo_path: str = ".", since: str = "HEAD~1") -> dict:
 
 @mcp.tool()
 def get_ir_summary(repo_path: str = ".") -> dict:
-    """Deterministic symbol-level IR summary for Java repositories.
+    """Deterministic symbol-level IR summary for Java repositories. Java only.
 
     Maps to: sourcecode repo-ir <repo_path> --summary-only
-    Returns: analysis summary, impact, and change_set — omits full graph nodes/edges.
-    repo_path: absolute path to the repository (default: current working directory).
+    Returns: reverse_graph (top 10 hubs), route_surface (top 50 endpoints),
+             subsystems (top 15), impact, analysis. Full graph nodes/edges omitted.
+
+    Output is bounded to ~100 KB for LLM safety. For full IR (can exceed 10 MB
+    on large repos), use the CLI: sourcecode repo-ir <path> --output ir.json
+    Use get_compact_context or get_agent_context for non-Java repos.
+
+    repo_path: absolute path to the Java repository (default: current working directory).
     """
     if not isinstance(repo_path, str):
         return _err("repo_path must be a string", "INVALID_ARGUMENT")
@@ -237,6 +249,34 @@ def generate_tests_context(repo_path: str = ".", include_all: bool = False) -> d
     return _execute(args)
 
 
+@mcp.tool()
+def get_impact_context(repo_path: str = ".", target: str = "", depth: int = 4) -> dict:
+    """Blast-radius analysis: who calls a class and what breaks if it changes? Java only.
+
+    Maps to: sourcecode impact <target> <repo_path> [--depth <depth>]
+    Returns: direct_callers, indirect_callers, endpoints_affected,
+             transactional_boundaries_touched, risk_score, risk_level, stats.
+
+    Use this when:
+    - Planning a refactor: understand the full call chain before changing a class
+    - PR review: assess blast radius of a changed service or utility class
+    - Incident triage: find all paths that reach a faulty component
+
+    target: class name (simple or FQN) or Java file path. Examples:
+            "UserService", "org.example.UserService", "UserService.java"
+    repo_path: absolute path to the Java repository (default: current working directory).
+    depth: BFS depth for indirect caller traversal (1–8, default: 4).
+    """
+    if not isinstance(repo_path, str):
+        return _err("repo_path must be a string", "INVALID_ARGUMENT")
+    if not isinstance(target, str) or not target.strip():
+        return _err("target must be a non-empty class name or FQN", "INVALID_ARGUMENT")
+    if not isinstance(depth, int) or depth < 1 or depth > 8:
+        return _err("depth must be an integer between 1 and 8", "INVALID_ARGUMENT")
+    args = ["impact", target.strip(), repo_path, "--depth", str(depth)]
+    return _execute(args)
+
+
 _TELEMETRY_ACTIONS = frozenset({"status", "enable", "disable"})
 
 

sourcecode-1.31.13/src/sourcecode/output_budget.py

@@ -0,0 +1,157 @@
+"""output_budget.py — Progressive output trimming for LLM context safety.
+
+Single entry point: trim_to_budget(data, budget_bytes, label="").
+
+Protects against runaway output on large repos by progressively dropping
+or truncating lower-priority sections while preserving the highest-value signals.
+
+Trim priority (lowest → highest value, trimmed first):
+  1. Inner boost/match lists inside symptom_explain, transactional_boundaries, mybatis
+  2. Medium-value lists: code_notes, env_map, related_notes
+  3. High-cost sections: relevant_files, suspected_areas, key_dependencies
+  4. Last resort: drop non-essential sections entirely
+
+Always preserved: project_type, project_summary, architecture_summary, task,
+  goal, confidence, analysis_gaps, error, ci_decision, summary, warnings, hint.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+# Sections that must never be removed (structural identity + user-facing signals)
+_ALWAYS_KEEP: frozenset[str] = frozenset({
+    "task", "goal",
+    "project_type", "project_summary", "architecture_summary",
+    "schema_version",
+    "confidence", "confidence_summary", "analysis_gaps", "gaps",
+    "error", "error_code", "message",
+    "ci_decision", "summary",
+    "warnings", "hint", "_budget_note",
+})
+
+
+# Each step: (top_key, inner_key_or_None, max_items)
+# inner_key=None → trim/drop top_key itself
+# max_items=0    → drop the section entirely
+_TRIM_SCHEDULE: list[tuple[str, str | None, int]] = [
+    # Step 1 — trim inner lists in structured sections
+    ("symptom_explain",          "boosts",               10),
+    ("symptom_explain",          "content_matches",       5),
+    ("symptom_explain",          "commit_matches",        5),
+    ("symptom_explain",          "synonym_matches",       3),
+    ("transactional_boundaries", "classes",               5),
+    ("mybatis",                  "dto_mappers",           5),
+    # Step 2 — trim medium-value top-level lists
+    ("code_notes",               None,                    5),
+    ("env_map",                  None,                    5),
+    ("related_notes",            None,                    5),
+    # Step 3 — trim higher-cost sections
+    ("relevant_files",           None,                   15),
+    ("suspected_areas",          None,                   10),
+    ("key_dependencies",         None,                   10),
+    # Step 4 — more aggressive
+    ("relevant_files",           None,                    8),
+    ("key_dependencies",         None,                    5),
+    ("suspected_areas",          None,                    5),
+    ("symptom_explain",          "boosts",                0),  # drop inner list
+    # Step 5 — drop non-essential sections
+    ("symptom_explain",          None,                    0),
+    ("code_notes",               None,                    0),
+    ("env_map",                  None,                    0),
+    ("related_notes",            None,                    0),
+    ("angular_analysis",         None,                    0),
+    ("spring_profiles",          None,                    0),
+    ("execution_paths",          None,                    0),
+    ("dependency_graph_summary", None,                    0),
+    # Step 6 — last resort
+    ("relevant_files",           None,                    3),
+    ("suspected_areas",          None,                    0),
+    ("key_dependencies",         None,                    0),
+]
+
+
+def _serialized_size(data: Any) -> int:
+    """Byte size of JSON-serialized data (UTF-8)."""
+    return len(json.dumps(data, ensure_ascii=False).encode("utf-8"))
+
+
+def trim_to_budget(data: dict, budget_bytes: int, *, label: str = "") -> dict:
+    """Progressively trim *data* to fit within *budget_bytes*.
+
+    Preserves the highest-value sections. Adds ``_budget_note`` when trimming
+    occurs so callers can surface it to users.
+
+    Returns data unchanged if already within budget.
+    """
+    if _serialized_size(data) <= budget_bytes:
+        return data
+
+    result: dict = dict(data)
+    original_size = _serialized_size(result)
+    trimmed_sections: list[str] = []
+
+    for top_key, inner_key, max_items in _TRIM_SCHEDULE:
+        if _serialized_size(result) <= budget_bytes:
+            break
+
+        if top_key not in result or result[top_key] is None:
+            continue
+
+        section_val = result[top_key]
+
+        if inner_key is None:
+            # Trim or drop the top-level key
+            if max_items == 0:
+                if top_key in _ALWAYS_KEEP:
+                    continue
+                del result[top_key]
+                trimmed_sections.append(f"{top_key}:dropped")
+            elif isinstance(section_val, list) and len(section_val) > max_items:
+                result[top_key] = section_val[:max_items]
+                trimmed_sections.append(f"{top_key}≤{max_items}")
+        else:
+            # Trim or drop an inner list
+            if not isinstance(section_val, dict):
+                continue
+            if inner_key not in section_val:
+                continue
+            inner_val = section_val[inner_key]
+            if max_items == 0:
+                new_sec = dict(section_val)
+                del new_sec[inner_key]
+                result[top_key] = new_sec
+                trimmed_sections.append(f"{top_key}.{inner_key}:dropped")
+            elif isinstance(inner_val, list) and len(inner_val) > max_items:
+                new_sec = dict(section_val)
+                new_sec[inner_key] = inner_val[:max_items]
+                result[top_key] = new_sec
+                trimmed_sections.append(f"{top_key}.{inner_key}≤{max_items}")
+
+    final_size = _serialized_size(result)
+    if trimmed_sections:
+        note = (
+            f"Output trimmed {original_size // 1024}KB → {final_size // 1024}KB "
+            f"(budget {budget_bytes // 1024}KB). "
+            f"Trimmed: {', '.join(trimmed_sections)}. "
+            "Use --output <file> to capture full output."
+        )
+        if label:
+            note = f"[{label}] {note}"
+        result["_budget_note"] = note
+
+    return result
+
+
+# Budget constants (bytes) — used by CLI callers
+BUDGET_COMPACT    = 30_000   # compact/agent main cmd
+BUDGET_AGENT      = 40_000   # agent main cmd (slightly more headroom)
+BUDGET_FIX_BUG   = 100_000  # fix-bug (with or without --symptom)
+BUDGET_REVIEW_PR  = 100_000  # review-pr
+BUDGET_ONBOARD    = 30_000   # onboard
+BUDGET_EXPLAIN    = 30_000   # explain
+BUDGET_REFACTOR   = 50_000   # refactor
+BUDGET_DELTA      = 80_000   # delta (change impact context)
+BUDGET_IMPACT     = 50_000   # impact blast-radius command