sourcecode 3.2.1__py3-none-any.whl → 3.3.0__py3-none-any.whl

sourcecode/cli.py

@@ -149,6 +149,88 @@ def _check_pipeline_coherence(sm: "SourceMap") -> list[str]:  # type: ignore[nam
 
     return issues
 
+# ---------------------------------------------------------------------------
+# Command tiers — what we promise about a command, published where it is read
+# ---------------------------------------------------------------------------
+
+#: The support commitment behind every command — one authority for it, read by
+#: `--help`, by the README command table and by the user guide.
+#:
+#: A tier is a **stability** promise, never a value ranking. `posture` is the most
+#: differentiated capability in the product *and* it is experimental: its shape can
+#: still change under a minor, so nobody should gate a pipeline on it yet. Those are
+#: two facts, and collapsing them onto one axis is how a surface starts lying — the
+#: first panel of `--help` still says "start here" for the commands worth learning
+#: first, and this table says what each command's output is worth relying on.
+#:
+#: This is not the pricing tier: Free/Pro is a separate axis (docs/PRODUCT_TIERS.md)
+#: and gates repository size, never capability.
+#:
+#: Assigning the tiers is a later milestone's work (commands moving between them,
+#: `parked` disappearing from the default help). Naming them is what ships here, so
+#: the vocabulary exists before it is used against a command.
+COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
+    ("core", "contract stable within a major — safe to gate CI on", (
+        "endpoints", "spring-audit", "migrate-check",
+        "impact", "impact-chain", "pr-impact", "verify",
+    )),
+    ("supported", "maintained; fields are added, never removed without a major", (
+        "verify-edit", "review-pr", "plan", "compare", "delta", "contract-diff",
+        "fix-bug", "rename-class", "prepare-context", "onboard", "explain",
+        "export", "repo-ir", "validation", "modernize", "chunk-file",
+        "cold-start", "baseline", "activate", "config", "schema", "version",
+        "cache", "auth", "mcp", "telemetry",
+    )),
+    ("experimental", "shape may change in a minor — do not gate CI on it", (
+        "posture", "archetype", "retrieve",
+    )),
+    ("parked", "kept working, no longer developed", ()),
+)
+
+#: Tiers whose membership is short enough to name in `--help`. `supported` is the
+#: remainder by construction, and printing twenty-six names would bury the two lists
+#: a reader acts on.
+_TIERS_NAMED_IN_HELP = ("core", "experimental", "parked")
+
+
+def command_tier(name: str) -> "str | None":
+    """The tier of a registered command, or None when it is in no tier.
+
+    None is a defect, not a state: the battery fails on it. It is returned rather
+    than defaulted so an unassigned command can never be silently published as
+    `supported`.
+    """
+    for tier, _promise, members in COMMAND_TIERS:
+        if name in members:
+            return tier
+    return None
+
+
+def _tier_help_block() -> str:
+    """The tier table as `--help` prints it — generated from `COMMAND_TIERS`, because
+    a hand-written catalogue beside a generated one drifts (it is what left
+    `endpoints` unlisted while it shipped)."""
+    import textwrap
+
+    lines = ["[bold]Command tiers[/bold] [dim](a stability promise, not a value ranking):[/dim]"]
+    indent = " " * 4
+    for tier, promise, members in COMMAND_TIERS:
+        if tier not in _TIERS_NAMED_IN_HELP:
+            listed = "every other command in the panels below"
+        elif members:
+            listed = " · ".join(members)
+        else:
+            listed = "none today"
+        lines.append(f"  [bold]{tier:<14}[/bold]{promise}")
+        # Pre-wrapped so the renderer never breaks a command name at its hyphen.
+        wrapped = textwrap.fill(
+            listed, width=70, initial_indent=indent, subsequent_indent=indent,
+            break_on_hyphens=False, break_long_words=False,
+        )
+        lines.append(f"[dim]{wrapped}[/dim]")
+    return "\n".join(lines)
+
+
 def _build_help_text() -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -193,6 +275,8 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
 
 [dim]Every command is grouped in the panels below; full reference in docs/USER_GUIDE.md[/dim]
 
+{_tier_help_block()}
+
 [bold]Auth commands:[/bold]
   auth status                  [dim]# show current plan and auth state[/dim]
   auth logout                  [dim]# remove local credentials[/dim]
@@ -829,7 +913,7 @@ try:
 except Exception:
     pass
 
-telemetry_app = typer.Typer(help="Manage anonymous telemetry (on by default; opt-out).", rich_markup_mode="rich")
+telemetry_app = typer.Typer(help="Manage anonymous telemetry (off by default; opt-in).", rich_markup_mode="rich")
 app.add_typer(telemetry_app, name="telemetry")
 
 mcp_app = typer.Typer(help="MCP integration: setup, status, serve, remove.", rich_markup_mode="rich")
@@ -857,8 +941,9 @@ app.add_typer(retrieve_app, name="retrieve")
 def _maybe_show_telemetry_notice() -> None:
     """Show first-run telemetry notice once, on interactive TTYs only.
 
-    Telemetry is on by default (opt-out). We inform rather than ask, then
-    mark the notice as shown so it appears only once.
+    Telemetry is off by default (opt-in). The notice is an invitation, not a
+    disclosure: nothing has been collected when it appears. Marked as shown so it
+    appears only once.
     """
     try:
         from sourcecode.telemetry.config import has_been_asked, mark_asked
@@ -1699,12 +1784,21 @@ def main(
                 f"ex={_excl_key},depth={effective_depth}"
             )
             _core_h = _hashlib.sha256(_core_flags_str.encode()).hexdigest()[:8]
-            if _git_sha and _git_root_str:
-                _core_key = f"{_git_sha}-{_core_h}"
+            # Freshness comes from ONE authority (cache.worktree_signature): the exact
+            # tree state an analysis would read, not the committed HEAD. Keyed on HEAD,
+            # this cache answered for a tree it had not read — an uncommitted pom.xml
+            # gaining a dependency was served the pre-edit analysis with is_stale:false.
+            # Clean tree → the sha, so the ordinary repeat run still hits.
+            _tree_sig = _cache_mod.worktree_signature(
+                Path(_git_root_str) if _git_root_str else target,
+                scope=target,
+            )
+            if _tree_sig:
+                _core_key = f"{_tree_sig}-{_core_h}"
             else:
-                # No git history (untracked/no-commit repo) — stable synthetic key
-                # scoped per repo path via cache_dir(); invalidated by --no-cache or cache clear.
-                _core_key = f"nogit-{_core_h}"
+                # The tree cannot be described (no git, unreadable) — a stable synthetic
+                # key would answer forever from the first run, so skip the cache instead.
+                _core_key = ""
 
             # ── View flags: output presentation only (no re-analysis needed) ──
             _view_flags_str = (
@@ -1719,7 +1813,7 @@ def main(
 
             # ── Lookup ──────────────────────────────────────────────────────
             # Step 1: try L1 to obtain the core_hash needed for L2 key
-            _l1_result = _cache_mod.read_core(target, _core_key)
+            _l1_result = _cache_mod.read_core(target, _core_key) if _core_key else None
 
             # Additive overlays (--env-map / --git-context) miss L1 because they sit in
             # the core key, yet neither changes the semantic core — env walks config
@@ -1735,8 +1829,8 @@ def main(
             # we inject exactly the overlays we flipped to land the hit.
             _l1_needs_env_inject = False
             _l1_needs_git_inject = False
-            if _l1_result is None and (env_map or git_context):
-                _sha_prefix = _git_sha if _git_sha else "nogit"
+            if _l1_result is None and _core_key and (env_map or git_context):
+                _sha_prefix = _tree_sig
                 _flippable = []
                 if git_context:
                     _flippable.append("gc")   # inject git is cheap + additive
@@ -3292,10 +3386,11 @@ def prepare_context_cmd(
     from dataclasses import asdict
     import time as _time
 
-    # Task-level cache: keyed on (task, git_head, symptom) so warm calls complete in <1s.
+    # Task-level cache: keyed on (task, tree state, symptom) so warm calls complete in <1s.
+    # The tree state comes from the same authority as every other layer, so an
+    # uncommitted edit invalidates here exactly as it does for the root command.
     # Skip for diff-dependent tasks (delta, review-pr), fast mode, and llm_prompt
     # (those embed per-call content that must not be served from cache).
-    import subprocess as _pctx_sub
     import hashlib as _pctx_hash
     from sourcecode import cache as _pctx_cache
     _pctx_git_sha = ""
@@ -3303,15 +3398,19 @@ def prepare_context_cmd(
     _pctx_cacheable = task not in ("delta", "review-pr") and not fast and not llm_prompt
     if _pctx_cacheable:
         try:
-            _sha_r2 = _pctx_sub.run(
-                ["git", "-C", str(target), "rev-parse", "--short", "HEAD"],
-                capture_output=True, text=True, timeout=3,
+            _pctx_git_sha = _pctx_cache.worktree_signature(
+                _resolve_repo_root(target), scope=target
             )
-            _pctx_git_sha = _sha_r2.stdout.strip()
         except Exception:
             pass
         if _pctx_git_sha:
-            _sym_h = _pctx_hash.sha256((symptom or "").encode()).hexdigest()[:8]
+            # Every option that changes the answer belongs in the key. --all and
+            # --include-config did not, and went unnoticed only because the key
+            # required a git sha: in a non-git tree nothing was cached at all, so
+            # the collision could not surface.
+            _sym_h = _pctx_hash.sha256(
+                f"sym={symptom or ''};all={all_gaps};cfg={include_config}".encode()
+            ).hexdigest()[:8]
             _pctx_cache_key = f"pctx-{task}-{_pctx_git_sha}-{_sym_h}-{format or 'json'}"
             _cached_pctx = _pctx_cache.read(target, _pctx_cache_key)
             if _cached_pctx is not None:
@@ -3743,16 +3842,22 @@ def prepare_context_cmd(
 @telemetry_app.command("status")
 def telemetry_status() -> None:
     """Show current telemetry setting."""
-    from sourcecode.telemetry.config import config_file_path, has_been_asked, is_enabled
+    from sourcecode.telemetry.config import config_file_path, is_enabled, stored_choice
     enabled = is_enabled()
-    asked = has_been_asked()
+    choice = stored_choice()
     status = "enabled" if enabled else "disabled"
-    typer.echo(f"Telemetry: {status} (on by default; opt-out)")
-    if not asked:
-        typer.echo("  (first-run notice not yet shown — will show on next run)")
+    typer.echo(f"Telemetry: {status} (off by default; opt-in)")
+    # "off because you said so" and "off because nobody asked you" are different
+    # answers, and a buyer auditing this needs to be told which one they have.
+    if choice is None:
+        typer.echo("  No choice recorded — nothing has been collected or sent.")
+    else:
+        typer.echo(f"  Your recorded choice: {'enabled' if choice else 'disabled'}.")
     typer.echo(f"  Config: {config_file_path()}")
-    typer.echo("  Disable: ask telemetry disable")
-    typer.echo("  Or set env var: SOURCECODE_TELEMETRY=0  (or DO_NOT_TRACK=1)")
+    if enabled:
+        typer.echo("  Disable: ask telemetry disable  (or SOURCECODE_TELEMETRY=0, DO_NOT_TRACK=1)")
+    else:
+        typer.echo("  Enable:  ask telemetry enable   (or SOURCECODE_TELEMETRY=1)")
 
 
 @telemetry_app.command("enable")
@@ -3774,7 +3879,7 @@ def telemetry_disable() -> None:
     from sourcecode.telemetry.config import set_enabled
     set_enabled(False)
     typer.echo("Telemetry disabled. No data will be collected or sent.")
-    typer.echo("Telemetry is on by default; this opt-out is remembered.")
+    typer.echo("Telemetry is off by default; this choice is recorded so the notice stops asking.")
     typer.echo("Re-enable at any time: ask telemetry enable")
 
 
@@ -8000,47 +8105,44 @@ def auth_status_cmd() -> None:
     """Show current authentication and plan status."""
     import json as _json
     try:
-        from sourcecode.license import (
-            _PRO_UNLOCK_ALL as _unlock,
-            _license_data as _ld,
-            is_pro as _ip,
-        )
+        from sourcecode.license import _license_data as _ld, entitlement as _entitlement
+        _ent = _entitlement()
     except Exception:
         _ld = None
-        _ip = False
-        _unlock = False
-
-    # While the early-adoption unlock is on, every Pro command runs. Reporting
-    # `pro: false` here contradicted the --help header and the commands' own
-    # behaviour: the status has to describe the gating that is actually in force,
-    # not the credential that happens to be absent.
-    _gating = {
-        "pro_gating": "disabled" if _unlock else "enabled",
-        "pro_effective": bool(_ip or _unlock),
-    }
-    if _unlock:
-        _gating["pro_reason"] = "early-adoption unlock: Pro commands run without a license"
-
-    if not _ld:
-        out: dict = {
-            "status": "unauthenticated",
-            "pro": bool(_unlock),
-            **_gating,
+        _ent = {
+            "entitlement": "free", "source": "free_tier", "authenticated": False,
+            "paywall_active": True, "when_it_changes": "", "free_repo_java_file_limit": None,
         }
-        sys.stdout.write(_json.dumps(out, ensure_ascii=False) + "\n")
-        sys.stdout.flush()
-        return
 
-    out = {
-        "status": "authenticated",
-        "auth_method": _ld.get("auth_method", "license_key"),
-        "email": _ld.get("email", ""),
-        "plan": _ld.get("plan", "unknown"),
-        "plan_status": _ld.get("status", "unknown"),
-        "pro": _ip,
-        "validated_at": _ld.get("validated_at") or _ld.get("activated_at") or "",
-        **_gating,
+    # P-2: one authority (`license.entitlement`) answers "what runs here, and why".
+    # The legacy keys below are *derived* from it rather than computed a second
+    # time — that is what stops `{"status": "unauthenticated", "pro": true}` from
+    # reappearing. They are deprecated and will be removed in a future major.
+    _pro = _ent["entitlement"] == "pro"
+    _legacy = {
+        "pro": _pro,
+        "pro_effective": _pro,
+        "pro_gating": "enabled" if _ent["paywall_active"] else "disabled",
+    }
+    if _ent["source"] == "early_adoption_unlock":
+        _legacy["pro_reason"] = "early-adoption unlock: Pro commands run without a license"
+
+    out: dict = {
+        "status": "authenticated" if _ent["authenticated"] else "unauthenticated",
+        **_ent,
+        **_legacy,
+        "deprecated_fields": ["pro", "pro_effective", "pro_gating", "pro_reason"],
     }
+    if _ld:
+        out.update({
+            "auth_method": _ld.get("auth_method", "license_key"),
+            "email": _ld.get("email", ""),
+            "plan": _ld.get("plan", "unknown"),
+            # The authority reads a missing status as active, so reporting
+            # "unknown" here would contradict the entitlement in the same object.
+            "plan_status": _ld.get("status", "active"),
+            "validated_at": _ld.get("validated_at") or _ld.get("activated_at") or "",
+        })
     sys.stdout.write(_json.dumps(out, indent=2, ensure_ascii=False) + "\n")
     sys.stdout.flush()
 
@@ -8172,7 +8274,7 @@ def config_cmd() -> None:
     from sourcecode.telemetry.config import config_file_path, is_enabled
     typer.echo(f"ask {__version__}")
     typer.echo(f"Config:    {config_file_path()}")
-    typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'}")
+    typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'} (off by default; opt-in)")
     typer.echo("")
     typer.echo("Manage telemetry:")
     typer.echo("  ask telemetry enable")
@@ -9300,17 +9402,32 @@ def cache_warm_cmd(
 ) -> None:
     """Pre-populate the cache by running a fresh analysis.
 
-    Runs a full analysis to populate L1/L2 caches and rebuild the RIS
-    (Repository Intelligence Snapshot). Useful after a merge/pull in CI.
+    Runs a full analysis to populate the snapshot cache, rebuild the RIS and build
+    the shared Canonical IR. Useful after a merge/pull in CI.
+
+    \b
+    It is not a general warm, and it says so when it finishes: it warms the
+    compact view (add --agent for the agent view), and analysis flags that change
+    what is analysed — --env-map, --depth N, --exclude — rescan anyway. Run
+    `ask cache model` for what a warm gives each command.
+
+    \b
+    In CI without a persisted cache directory, every pipeline pays the cold cost
+    this command reports. Cache ~/.sourcecode/cache and ~/.sourcecode between jobs,
+    or budget the cold run explicitly.
     """
     import shutil as _shutil
     import subprocess as _sub
+    import time as _warm_time
     # Warm exactly the path given. Resolving up to the enclosing git root warmed
     # (and reported on) the whole monorepo when asked for one module — every other
     # command scopes to the argument, so `cache warm ./service-a` populated a cache
     # for a different target than `ask ./service-a` reads.
     target = Path(path).resolve()
     _git_root = _resolve_repo_root(Path(path))
+    # Cost is reported for the whole warm, the CIR build included — that is what a
+    # pipeline pays, and quoting only the analysis half would understate it (C4-5).
+    _warm_t0 = _warm_time.monotonic()
     typer.echo(f"Warming cache for {target} …", err=True)
     if _git_root != target:
         typer.echo(
@@ -9345,6 +9462,58 @@ def cache_warm_cmd(
             err=True,
         )
 
+    # A warm that reports only what it built lets the reader assume it built
+    # everything — which is how "el warm no es un warm general" became a field
+    # finding (C4-3) rather than a documented limit. State both halves, and state
+    # the cost, because in CI it is paid per pipeline (C4-5).
+    _warm_elapsed = _warm_time.monotonic() - _warm_t0
+    _warmed_view = "compact + agent views" if (compact and agent) else (
+        "agent view" if agent else "compact view"
+    )
+    typer.echo(
+        f"Warmed in {_warm_elapsed:.0f}s: {_warmed_view}, RIS, shared CIR, parse cache.",
+        err=True,
+    )
+    typer.echo(
+        "NOT warmed: prepare-context task answers (refactor / fix-bug / generate-tests / "
+        "delta / review-pr), and any run whose analysis flags differ (--env-map, --depth N, "
+        "--exclude) — those rescan. Measured: `endpoints` and `migrate-check` gain nothing "
+        "from a warm. `ask cache model` says what a warm gives each command.",
+        err=True,
+    )
+    typer.echo(
+        f"In CI without a persisted ~/.sourcecode, every pipeline pays this {_warm_elapsed:.0f}s again.",
+        err=True,
+    )
+
+
+@cache_app.command("model")
+def cache_model_cmd(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+    markdown: bool = typer.Option(False, "--markdown", help="Output the tables published in the user guide."),
+) -> None:
+    """What each cache layer stores, what invalidates it, and what a warm helps.
+
+    \b
+    Answers, per command, the question a warm raises: will this be fast next time?
+      the answer      — a warm stores what this command returns
+      the shared work — a warm removes the Java parse / the shared IR; the command
+                        still computes its own answer
+      nothing         — a warm does not touch it
+
+    One rule covers invalidation: every layer keys on the exact tree state, so any
+    change to the analysed files invalidates it, committed or not.
+    """
+    from sourcecode import cache_model as _cmodel
+
+    if json_output:
+        import json as _j
+        typer.echo(_j.dumps(_cmodel.as_dict(), indent=2, ensure_ascii=False))
+    elif markdown:
+        typer.echo(_cmodel.render_markdown())
+    else:
+        typer.echo(_cmodel.render_text())
+
 
 @cache_app.command("freshness")
 def cache_freshness_cmd(

sourcecode/context_cache.py

@@ -190,34 +190,14 @@ def _git_head(repo_root: Path) -> str:
 def _worktree_signature(repo_root: Path) -> str:
     """Deterministic fingerprint of the *exact* tree state.
 
-    committed HEAD, plus — only when the tree is dirty — a hash of the porcelain
-    status and the diff against HEAD. Two identical tree states yield the same
-    signature (correct reuse); any tracked edit changes it (correct invalidation).
-    Returns ``""`` when the path is not a git repo (caller disables caching).
+    Thin alias of the one authority, :func:`sourcecode.cache.worktree_signature`.
+    It used to be a second implementation living here, which is how the two caches
+    ended up invalidating on different facts: this one on the tree, the snapshot
+    cache on the committed HEAD alone.
     """
-    head = _git_head(repo_root)
-    if not head:
-        return ""
-    try:
-        status = subprocess.run(
-            ["git", "-C", str(repo_root), "status", "--porcelain"],
-            capture_output=True, text=True, timeout=5,
-        )
-        porcelain = status.stdout if status.returncode == 0 else ""
-    except Exception:
-        porcelain = ""
-    if not porcelain.strip():
-        return head  # clean tree — HEAD fully describes it
-    try:
-        diff = subprocess.run(
-            ["git", "-C", str(repo_root), "diff", "HEAD"],
-            capture_output=True, text=True, timeout=10,
-        )
-        diff_txt = diff.stdout if diff.returncode == 0 else ""
-    except Exception:
-        diff_txt = ""
-    dirty = hashlib.sha256((porcelain + "\x00" + diff_txt).encode("utf-8", "replace")).hexdigest()[:16]
-    return f"{head}+dirty:{dirty}"
+    from sourcecode.cache import worktree_signature
+
+    return worktree_signature(repo_root)
 
 
 def _options_fingerprint(options: Optional[dict[str, Any]]) -> str:

sourcecode/license.py

@@ -376,16 +376,78 @@ def _maybe_revalidate() -> None:
         pass
 
 
-def _init() -> None:
-    global _license_data, is_pro
-    _license_data = _load_license_file()
-    is_pro = (
+def entitlement() -> dict:
+    """The one answer to "what runs here today, and why" (P-2).
+
+    `auth status` used to publish four fields about this — `status`, `pro`,
+    `pro_gating`, `pro_effective`, plus a `pro_reason` sentence — and they read as
+    a contradiction: `{"status": "unauthenticated", "pro": true}`. Each field was
+    true on its own axis; together they told a buyer nothing about what they have,
+    why they have it, or what changes when it ends. That is the ADR-0008 pattern
+    exactly, on the commercial surface instead of an analysis one.
+
+    Every published entitlement field is derived from this dict and nowhere else.
+
+    Keys:
+      entitlement        "pro" | "free" — what actually runs right now
+      source             why: "license_key" | "early_adoption_unlock" | "free_tier"
+      authenticated      whether a credential is on this machine (an independent
+                         fact: today one can be entitled to Pro without one)
+      paywall_active     whether the paywall is enforcing anything at all
+      when_it_changes    what a user loses when `source` stops applying, in the
+                         terms the gate actually uses — never a price
+      free_repo_java_file_limit
+                         the number the size gate compares against
+    """
+    authenticated = _license_data is not None
+    licensed = bool(
         _license_data is not None
         and _license_data.get("plan") == "pro"
         and _license_data.get("status", "active") != "inactive"
     )
-    if _PRO_UNLOCK_ALL:
-        is_pro = True  # TEMPORARY: early-adoption Pro unlock (see _PRO_UNLOCK_ALL)
+    if licensed:
+        source = "license_key"
+    elif _PRO_UNLOCK_ALL:
+        source = "early_adoption_unlock"
+    else:
+        source = "free_tier"
+
+    if source == "license_key":
+        when = "Your licence entitles you to Pro; nothing changes while it stays active."
+    elif source == "early_adoption_unlock":
+        when = (
+            "Pro runs without a licence during early adoption. When that ends, every command "
+            f"still runs at full output on repositories up to {_FREE_REPO_JAVA_FILE_LIMIT} Java "
+            "source files; above that, the heavy-analysis commands ask for Pro. Capability is "
+            "never what is gated — size, automation and team are."
+        )
+    else:
+        when = (
+            f"Every command runs at full output on repositories up to {_FREE_REPO_JAVA_FILE_LIMIT} "
+            "Java source files. Above that, the heavy-analysis commands require Pro."
+        )
+
+    return {
+        "entitlement": "pro" if (licensed or _PRO_UNLOCK_ALL) else "free",
+        "source": source,
+        "authenticated": authenticated,
+        "paywall_active": not _PRO_UNLOCK_ALL,
+        "when_it_changes": when,
+        "free_repo_java_file_limit": _FREE_REPO_JAVA_FILE_LIMIT,
+    }
+
+
+def _init() -> None:
+    """Load the credential and derive the entitlement from the one authority.
+
+    `is_pro` is what every gate reads (`can_use`, `require_feature`), and it is
+    computed here from `entitlement()` rather than beside it — a second copy of
+    this rule is how `auth status` came to publish a state the commands
+    contradicted (P-2).
+    """
+    global _license_data, is_pro
+    _license_data = _load_license_file()
+    is_pro = entitlement()["entitlement"] == "pro"
 
 
 _init()
@@ -396,7 +458,7 @@ _init()
 # ---------------------------------------------------------------------------
 
 def _emit_telemetry(event: str, **kw: object) -> None:
-    """Best-effort telemetry emit. Respects the user's opt-out; never raises or blocks."""
+    """Best-effort telemetry emit. Sends nothing unless the user opted in; never raises or blocks."""
     try:
         from sourcecode import telemetry as _tel
         _tel.record(event, **kw)  # type: ignore[arg-type]

sourcecode/mcp/server.py

@@ -33,8 +33,8 @@ def _record_tool_invocation(name: Any, success: bool, started: float) -> None:
 
     Aggregate only: which of our own tools ran, whether it succeeded, and a
     duration bucket. Never the arguments — those carry repository paths — and
-    never any result content. Honours the same opt-out as every other event
-    (`ask telemetry disable`, SOURCECODE_TELEMETRY=0, DO_NOT_TRACK=1); when
+    never any result content. Honours the same opt-in as every other event
+    (off until `ask telemetry enable` or SOURCECODE_TELEMETRY=1); when
     telemetry is off, `record` returns before building anything.
     """
     try:

sourcecode/prepare_context.py

@@ -1090,20 +1090,20 @@ class TaskContextBuilder:
     def _try_ris_fast_path(self, task_name: str, spec: "TaskSpec") -> Optional[TaskOutput]:
         """Return TaskOutput from a warm RIS without running the full scan.
 
-        Only activated for onboard/explain when git HEAD matches stored RIS.
+        Only activated for onboard/explain when the stored RIS describes the tree
+        on disk — the same freshness authority every cache layer keys on, not the
+        committed HEAD (which served this fast path through uncommitted edits).
         Falls through (returns None) on any error or cache miss.
         """
         try:
-            import subprocess as _sp
             from sourcecode.ris import load_ris as _lris
+            from sourcecode.ris import _tree_signature as _ris_sig
             _ris = _lris(self.root)
             if _ris is None or not _ris.compact_summary:
                 return None
-            _r = _sp.run(
-                ["git", "-C", str(self.root), "rev-parse", "--short", "HEAD"],
-                capture_output=True, text=True, timeout=2,
-            )
-            if _r.returncode != 0 or _r.stdout.strip() != _ris.git_head:
+            _stored_sig = (_ris.metadata or {}).get("tree_signature") or ""
+            _current_sig = _ris_sig(self.root)
+            if not _stored_sig or not _current_sig or _stored_sig != _current_sig:
                 return None
 
             compact = _ris.compact_summary

sourcecode/ris.py

@@ -258,6 +258,7 @@ def _build_from_core(
                 1.0 if agent_data else (0.5 if compact_data else 0.0)
             ),
             "partial": not bool(agent_data),
+            "tree_signature": _tree_signature(repo_root),
         },
     )
 
@@ -295,6 +296,7 @@ def maybe_update_ris(repo_root: Path, core_dict: dict, git_head: str) -> None:
                     "snapshot_source": "existing_snapshot_system",
                     "confidence": float(1.0 if agent_data else (0.5 if compact_data else 0.0)),
                     "partial": not bool(agent_data),
+                    "tree_signature": _tree_signature(repo_root),
                 },
             )
             save_ris(repo_root, updated)
@@ -433,6 +435,21 @@ def _current_git_head(repo_root: Path) -> str:
     return ""
 
 
+def _tree_signature(repo_root: Path) -> str:
+    """Tree state this snapshot describes — the one freshness authority.
+
+    Stored in ``metadata["tree_signature"]`` at write time so staleness compares
+    the tree the RIS was built from against the tree on disk now. HEAD alone
+    called a snapshot fresh while uncommitted edits made it describe nothing.
+    """
+    try:
+        from sourcecode.cache import worktree_signature
+
+        return worktree_signature(repo_root)
+    except Exception:
+        return ""
+
+
 def _has_uncommitted_changes(repo_root: Path) -> bool:
     """Return True if working tree has staged or unstaged changes to tracked files.
 
@@ -465,8 +482,17 @@ def get_cold_start_context(repo_root: Path) -> dict:
             return {"status": "no_ris"}
 
         current_head = _current_git_head(repo_root)
-        stale = bool(current_head and ris.git_head and current_head != ris.git_head)
         uncommitted = _has_uncommitted_changes(repo_root)
+        # Staleness is about the tree the snapshot describes, not the commit it was
+        # taken at: with HEAD alone a snapshot stayed `stale: false` through every
+        # uncommitted edit. Snapshots written before the signature existed fall back
+        # to the pair of facts that were available then.
+        _stored_sig = (ris.metadata or {}).get("tree_signature") or ""
+        _current_sig = _tree_signature(repo_root)
+        if _stored_sig and _current_sig:
+            stale = _stored_sig != _current_sig
+        else:
+            stale = bool(current_head and ris.git_head and current_head != ris.git_head) or uncommitted
 
         endpoints = ris.api_surface.get("endpoints", [])
         _is_java = (