sourcecode 5.9.31__py3-none-any.whl → 5.9.32__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.9.31"
+__version__ = "5.9.32"

sourcecode/_build_commit.py

@@ -1,5 +1,5 @@
 """Generated at build time by hatch_build.py. Do not edit (AUD-592-D04)."""
 
-BUILD_COMMIT = '1cca45c9b950c882c44b7a21aaad5e230cdddab7'
+BUILD_COMMIT = '904d896034a9ad785a80f37014d87e2b412cf1bd'
 CLOSURE_PROVENANCE = {'AUD-611-B05': {'commit': '', 'status': 'uncited'}, 'AUD-611-B06': {'commit': '', 'status': 'uncited'}, 'AUD-611-B07': {'commit': '', 'status': 'uncited'}, 'AUD-611-B08': {'commit': '', 'status': 'uncited'}, 'AUD-611-B09': {'commit': '', 'status': 'uncited'}, 'AUD-611-B10': {'commit': '', 'status': 'uncited'}, 'AUD-611-B11': {'commit': '', 'status': 'uncited'}, 'AUD-612-07': {'commit': '', 'status': 'uncited'}, 'AUD-612-09': {'commit': '', 'status': 'uncited'}, 'AUD-612-14': {'commit': '', 'status': 'uncited'}, 'AUD-612-B03': {'commit': '', 'status': 'uncited'}, 'AUD-612-B07': {'commit': '', 'status': 'uncited'}, 'AUD-612-B13': {'commit': '', 'status': 'uncited'}, 'AUD-612-E': {'commit': '', 'status': 'uncited'}, 'AUD-612-G': {'commit': '', 'status': 'uncited'}, 'AUD-612-I': {'commit': '', 'status': 'uncited'}, 'AUD-612-K': {'commit': '', 'status': 'uncited'}, 'AUD-612-M': {'commit': '', 'status': 'uncited'}, 'AUD-612-R': {'commit': '', 'status': 'uncited'}, 'AUD-613-ROOT': {'commit': '', 'status': 'uncited'}, 'AUD-614-07': {'commit': '', 'status': 'uncited'}, 'AUD-614-E': {'commit': '', 'status': 'uncited'}, 'AUD-614-F': {'commit': '', 'status': 'uncited'}, 'AUD-614-G': {'commit': '', 'status': 'uncited'}, 'AUD-614-I': {'commit': '', 'status': 'uncited'}, 'AUD-614-INTENT-TIE': {'commit': '', 'status': 'uncited'}, 'AUD-614-JUNIT4': {'commit': '', 'status': 'uncited'}, 'AUD-614-RISK-L0': {'commit': '', 'status': 'uncited'}, 'AUD-614-SELFTEST-TIMEOUT': {'commit': '', 'status': 'uncited'}, 'AUD-615-07': {'commit': '', 'status': 'uncited'}, 'AUD-615-COLD-COMPACT': {'commit': '', 'status': 'uncited'}, 'AUD-615-DRIFT': {'commit': '', 'status': 'uncited'}, 'AUD-615-E': {'commit': '', 'status': 'uncited'}, 'AUD-615-F': {'commit': '', 'status': 'uncited'}, 'AUD-615-INTENT-TIE': {'commit': '', 'status': 'uncited'}, 'AUD-615-JUNIT4': {'commit': '', 'status': 'uncited'}, 'AUD-615-RISK-L0': {'commit': '', 'status': 'uncited'}, 'AUD-615-SELFTEST-TIMEOUT': {'commit': '', 'status': 'uncited'}, 'AUD-616-E-PROV': {'commit': '', 'status': 'uncited'}, 'AUD-616-F, -RISK-L0, -SELFTEST-TIMEOUT, -INTENT-TIE, -DRIFT, -COLD-COMPACT, -E, -07': {'commit': '', 'status': 'uncited'}, 'AUD-616-INTENT-TIE-COV': {'commit': '', 'status': 'uncited'}, 'AUD-616-JUNIT4-SELF': {'commit': '', 'status': 'uncited'}, 'AUD-616-KOTLIN': {'commit': '', 'status': 'uncited'}, 'AUD-616-O': {'commit': '', 'status': 'uncited'}, 'AUD-616-P': {'commit': '', 'status': 'uncited'}, 'Suite hygiene': {'commit': '', 'status': 'uncited'}, 'Window': {'commit': '', 'status': 'uncited'}, '`ALT-08` (arithmetic half)': {'commit': '', 'status': 'uncited'}, '`ALT-25`': {'commit': '', 'status': 'uncited'}, '`ASK-FIELD-01`': {'commit': '829f9fa', 'status': 'present'}, '`ASK-FIELD-02`': {'commit': '6a659fa', 'status': 'present'}, '`ASK-FIELD-03`': {'commit': '55b0d51', 'status': 'present'}, '`AUD-588-F05`': {'commit': '470e4a4', 'status': 'present'}, '`AUD-590-B01` / `B-01`, `F-01`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B02` / `B-02`, `F-02`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B03` / `B-03`, `F-03`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B04` / `B-04`, `F-04`': {'commit': '', 'status': 'uncited'}, '`AUD-590-R01` / `R-01`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A01` / `A-1`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A02` / `A-2`, `A-4`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A03` / `A-3`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A05` / `A-5`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A06` / `A-6`, `A-7`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A08` / `A-8`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A09` / `A-9`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A10` / `A-10`': {'commit': '', 'status': 'uncited'}, '`AUD-592-A02` / `A-1` second half, `§12.5`': {'commit': '63f3d61', 'status': 'present'}, '`AUD-592-B01` / `B-8`': {'commit': '8329614', 'status': 'present'}, '`AUD-592-D01` / `D-1`': {'commit': '0f8e03f', 'status': 'present'}, '`AUD-592-D02` / `D-2`': {'commit': '1d3db4d', 'status': 'present'}, '`AUD-592-D03` / `D-3`': {'commit': 'f28fe40', 'status': 'present'}, '`AUD-592-R01` / `A-1`': {'commit': '216025f', 'status': 'present'}, '`AUD-592-R02` / `N-4`, reopens `AUD-513-N04`': {'commit': 'ec3050d', 'status': 'present'}, '`AUD-593-N01` / `N-01`': {'commit': 'dd6a706', 'status': 'present'}, '`AUD-593-N02` / `N-02`': {'commit': 'f539787', 'status': 'present'}, '`AUD-593-N03` / `N-03`': {'commit': '1dd0b1c', 'status': 'present'}, '`AUD-593-N05` / `N-05`': {'commit': 'aa89388', 'status': 'present'}, '`AUD-593-N06` / `N-06`': {'commit': 'aa584a6', 'status': 'present'}, '`AUD-594-N04` / `D-5`, disclosure half of `B-3`': {'commit': 'a0060b7', 'status': 'present'}, '`AUD-594-X01` / `A-1`, residual of `AUD-593-N03`': {'commit': 'dd222b9', 'status': 'present'}, '`AUD-594-X02` / `A-1` second half': {'commit': '1193937', 'status': 'present'}, '`AUD-594-X03` / `X-03`, residual of `AUD-593-N01`': {'commit': 'e89e8f0', 'status': 'present'}, '`AUD-594-X04`': {'commit': '05b8cc9', 'status': 'present'}, '`AUD-595-A02` / `N-5`, advisory half of `AUD-588-B11`': {'commit': '3e15227', 'status': 'present'}, '`AUD-595-A03` / `B-6` exit-code half': {'commit': 'ab7285f', 'status': 'present'}, '`AUD-595-A05`': {'commit': 'e0b3d10', 'status': 'present'}, '`AUD-595-A07`, narrow half of `AUD-592-A02`': {'commit': 'cc15177', 'status': 'present'}, '`AUD-595-B01` / §B': {'commit': 'b77a1ad', 'status': 'present'}, '`AUD-595-Q01`': {'commit': '91a6566', 'status': 'present'}, '`AUD-596-A01` / `ASK-DET-001`': {'commit': 'fa508b4', 'status': 'present'}, '`AUD-596-A02` / `ASK-SELF-001`': {'commit': '4dfadc8', 'status': 'present'}, '`AUD-596-A03` / `ASK-C1-001`': {'commit': 'bffa3a6', 'status': 'present'}, '`AUD-596-A04` / `ASK-UX-003` + `ASK-UX-004`': {'commit': 'f0aac3c', 'status': 'present'}, '`AUD-596-B01` / `B-01`, harder witness for `BUG-6`': {'commit': '567d09d', 'status': 'present'}, '`AUD-596-B02` / `B-02`, class residual of `R2`': {'commit': '', 'status': 'uncited'}, '`AUD-596-B03` / `B-03`': {'commit': 'a8cb814', 'status': 'present'}, '`AUD-596-B06` / `B-06`': {'commit': '8107927', 'status': 'present'}, '`AUD-596-B07` / `B-07`, class residual of `AUD-592-R02`': {'commit': 'e060485', 'status': 'present'}, '`AUD-596-B09` / `B-09`': {'commit': '5b8146c', 'status': 'present'}, '`AUD-596-B10` / `B-10`': {'commit': '5cb994d', 'status': 'present'}, '`AUD-596-B16` / `B-16`': {'commit': '1507f69', 'status': 'present'}, '`AUD-596-D01` / `B-13` + `B-14`': {'commit': '0b1bdf0', 'status': 'present'}, '`AUD-596-D02` / `B-08`, residual of `AUD-594-N04`': {'commit': 'e7f73c3', 'status': 'present'}, '`AUD-596-D03` / `ASK-AGT-001`': {'commit': '8c46967', 'status': 'present'}, '`AUD-596-D04` / `B-18`': {'commit': '040f027', 'status': 'present'}, '`AUD-596-D05` / `B-19`': {'commit': 'fd2bf68', 'status': 'present'}, '`AUD-596-D06` / `B-20`': {'commit': '784cd83', 'status': 'present'}, '`AUD-596-D07` / `B-17`, half refuted': {'commit': 'c3ff822', 'status': 'present'}, '`AUD-596-D08` / `B-22`, class residual of `AUD-591-A06`': {'commit': 'b396c6a', 'status': 'present'}, '`AUD-596-D09` / `B-23`, surviving half of `B26`': {'commit': 'fd3d63f', 'status': 'present'}, '`AUD-596-D10` / `B-29`': {'commit': '', 'status': 'uncited'}, '`AUD-596-D11` / `ASK-UX-005`': {'commit': 'f4b4f77', 'status': 'present'}, '`AUD-596-D12` — six hints that send the reader back to the error': {'commit': '498df44', 'status': 'present'}, '`AUD-596-D13` / `B-28`': {'commit': '1014c72', 'status': 'present'}, '`AUD-596-D14` / `B-15`, narrow half of `B20`': {'commit': '10f2827', 'status': 'present'}, '`AUD-596-R01` / `B-05`': {'commit': '', 'status': 'uncited'}, '`AUD-596-X01` / `ASK-GATE-001`, gating half of `B24`': {'commit': 'e59c655', 'status': 'present'}, '`AUD-596-X02` / `ASK-UX-001` + `ASK-UX-002` + `B-21`': {'commit': 'f6ebf50', 'status': 'present'}, '`AUD-597-A01` / `ASK-UX-001` + `N-01`': {'commit': 'f8cf061', 'status': 'present'}, '`AUD-597-A02` / `ASK-UX-008` + `ASK-DOC-002`': {'commit': '9d47a4c', 'status': 'present'}, '`AUD-597-A03` / `ASK-DET-001`': {'commit': '4c7622a', 'status': 'present'}, '`AUD-597-A04` / `ASK-LEDGER-001`': {'commit': '46fb870', 'status': 'present'}, '`AUD-597-D01` / `B-04`': {'commit': '1094e6a', 'status': 'present'}, '`AUD-597-D02` / `ASK-DOC-001`': {'commit': 'ecb1bb7', 'status': 'present'}, '`AUD-597-D03` / `N-06`': {'commit': '9784333', 'status': 'present'}, '`AUD-597-D04` / `N-05`': {'commit': 'e51c087', 'status': 'present'}, '`AUD-597-D05` / `N-04`, fourth appearance of `C4-27`': {'commit': '9cccc15', 'status': 'present'}, '`AUD-597-D06` / `ASK-CLI-001`': {'commit': '178aa6d', 'status': 'present'}, '`AUD-597-D07` / `N-03`': {'commit': '9245e35', 'status': 'present'}, '`AUD-597-R01` / `ASK-PERF-001`': {'commit': '6910054', 'status': 'present'}, '`AUD-597-R02` / `ASK-ENC-001`': {'commit': 'ce6dac1', 'status': 'present'}, '`AUD-597-R03` / `ASK-UX-002`': {'commit': 'c57e50b', 'status': 'present'}, '`AUD-597-X01` / `ASK-BUILD-001` + `ASK-META-001` / `B-12`': {'commit': '354338b', 'status': 'present'}, '`AUD-598-B01` / `ASK-META-001`': {'commit': 'b2f7c65', 'status': 'present'}, '`AUD-598-B02` / `ASK-UX-002`': {'commit': '56a4bf7', 'status': 'present'}, '`AUD-598-B03` / `B-11`': {'commit': 'c63cb24', 'status': 'present'}, '`AUD-598-B04` / `N-02`': {'commit': '187937f', 'status': 'present'}, '`AUD-598-R01` / `ASK-PERF-002`': {'commit': '', 'status': 'uncited'}, '`AUD-598-X01` / `N-01` + `B-13` + `B-14` + `B-29` + `N-06`': {'commit': '6f2f5a4', 'status': 'present'}, '`AUD-600-B01` / `P-01`': {'commit': '366ffed', 'status': 'present'}, '`AUD-600-B02` / `P-02` + `ASK-PACK-002`': {'commit': '2a814c3', 'status': 'present'}, '`AUD-600-B03` / `ASK-PACK-001`': {'commit': '452f2a0', 'status': 'present'}, '`AUD-600-D01`': {'commit': '1224e1b', 'status': 'present'}, '`AUD-600-D02`': {'commit': 'eab8172', 'status': 'present'}, '`AUD-600-R01` / `R-01`': {'commit': '88add64', 'status': 'present'}, '`AUD-601-B01` / `N-02`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-B02` / `ASK-PACK-004`': {'commit': '', 'status': 'uncited'}, '`AUD-601-D01` / `N-01`, `ASK-UX-001`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-D02` / `B-13`, `B-14`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-M01` / `B-26`, `B-27` retracted': {'commit': '', 'status': 'uncited'}, '`AUD-601-R01` / `R-02`': {'commit': '', 'status': 'uncited'}, '`AUD-619-WATCH`': {'commit': '', 'status': 'uncited'}, '`AUD-620-COMMAND-SURFACE`': {'commit': '', 'status': 'uncited'}, '`AUD-620-REVIEW-PR`': {'commit': '', 'status': 'uncited'}, '`AUD-621-REVIEW-PR`': {'commit': '', 'status': 'uncited'}, '`B-3`': {'commit': '773268d', 'status': 'present'}, '`B-6`': {'commit': '17c6e06', 'status': 'present'}, '`B-8`': {'commit': '8329614', 'status': 'present'}, '`BUG-03` (statement half)': {'commit': '', 'status': 'uncited'}, '`BUG-09`': {'commit': '', 'status': 'uncited'}, '`BUG-10` (Vert.x residual)': {'commit': '', 'status': 'uncited'}, '`BUG-13`': {'commit': '', 'status': 'uncited'}, '`BUG-13`, `BUG-15`, `BUG-17`, `BUG-21`, `BUG-08`, `BUG-10`/`BUG-23`': {'commit': '', 'status': 'uncited'}, '`BUG-14`': {'commit': '', 'status': 'uncited'}, '`BUG-15`': {'commit': '', 'status': 'uncited'}, '`BUG-16`': {'commit': '', 'status': 'uncited'}, '`BUG-20`': {'commit': '', 'status': 'uncited'}, '`BUG-21`': {'commit': '', 'status': 'uncited'}, '`BUG-3` / `443b345`': {'commit': '', 'status': 'uncited'}, '`BUG-4a` / `AUD-588-B11` residual': {'commit': '24b4185', 'status': 'present'}, '`BUG-4b` / `AUD-588-B11` residual': {'commit': '0376350', 'status': 'present'}, '`E-39`, class residual of `AUD-593-N06`': {'commit': '25fc11f', 'status': 'present'}, '`N-5`': {'commit': 'c68083f', 'status': 'present'}, '`N-7`': {'commit': '082e9de', 'status': 'present'}, '`NEW-01` (regime row)': {'commit': '', 'status': 'uncited'}, '`NEW-02` / `BUG-05`': {'commit': '', 'status': 'uncited'}, '`R-01-INFLIGHT` (stage capture)': {'commit': '', 'status': 'uncited'}, '`R-1`': {'commit': '424fb1c', 'status': 'present'}, '`R-2`': {'commit': '5158b92', 'status': 'present'}, '`R-3`': {'commit': '88aec04', 'status': 'present'}, '`R-4`': {'commit': '04fd04f', 'status': 'present'}, '`REG-01`': {'commit': '', 'status': 'uncited'}, '`REG-04`': {'commit': '', 'status': 'uncited'}, '`SEC-010` cost': {'commit': '', 'status': 'uncited'}, '`retrieve security-surface --target`': {'commit': '', 'status': 'uncited'}}
 CLOSURE_COVERAGE = {'closed_rows': 185, 'present': 91, 'absent': 0, 'unresolved': 0, 'uncited': 94, 'unknown': 0}

sourcecode/_docs/USER_GUIDE.md

@@ -279,7 +279,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.9.31
+# ask 5.9.32
 ```
 
 Requires Python 3.9+.

sourcecode/cli.py

@@ -1790,6 +1790,8 @@ def _emit_error_json(error: str, message: str, **context: object) -> None:
     All CLI validation and runtime errors must go through this helper so that
     agents and tools can parse stderr reliably regardless of error type.
     """
+    from sourcecode.telemetry.lifecycle import mark
+    mark("internal_error" if error in {"INTERNAL_ERROR", "EXECUTION_FAILED"} else "expected_error")
     import json as _json
     payload = build_error_envelope(error, message, **context)
     sys.stderr.write(_json.dumps(payload, ensure_ascii=_json_ensure_ascii()) + "\n")
@@ -4863,17 +4865,14 @@ def _get_command_with_preprocessing(typer_instance: Any) -> Any:
         "enrich", "audit-report", "audit-verify", "migrate-recipe", "data-exposure", "posture", "migrate-check",
         "impact-chain", "pr-impact", "explain", "onboard", "review-pr", "fix-bug", "modernize",
         "rename-class", "chunk-file", "activate", "selftest", "explain-endpoint", "regress", "version",
-        "schema", "config", "archetype", "cold-start", "telemetry", "mcp", "cache", "baseline",
+        "schema", "config", "update", "archetype", "cold-start", "telemetry", "mcp", "cache", "baseline",
         "auth", "retrieve", "prepare-context", "pack",
     })
 
     def _telemetry_command(args_for_command: Optional[list[str]]) -> str:
         """Extract only a registered CLI command, never a path or option value."""
         tokens = list(args_for_command) if args_for_command is not None else sys.argv[1:]
-        for token in tokens:
-            if token in _TELEMETRY_COMMANDS:
-                return token
-        return "analyze"
+        return tokens[0] if tokens and tokens[0] in _TELEMETRY_COMMANDS else "analyze"
 
     def _telemetry_flags(args_for_command: Optional[list[str]]) -> list[str]:
         tokens = list(args_for_command) if args_for_command is not None else sys.argv[1:]
@@ -4896,35 +4895,59 @@ def _get_command_with_preprocessing(typer_instance: Any) -> Any:
         # args=None → Click reads sys.argv; _preprocess_argv() in main_entry handled it.
         started = time.monotonic()
         command = _telemetry_command(args)
-        success = True
+        from sourcecode import telemetry as _tel
+        from sourcecode.telemetry.lifecycle import Execution, current, exit_outcome
+        parent = current.get()
+        scope = Execution(interface=parent.interface if parent else "cli",
+                          parent=parent.id if parent else "", command=command)
+        token = current.set(scope)
+        fields = dict(cmd=("mcp" if command == "mcp" else "telemetry" if command == "telemetry" else "analyze"),
+                      command=command, flags=_telemetry_flags(args))
+        _tel.record("execution_started", **fields, outcome="started")
         error_kind = None
         try:
-            return _orig_cmd_main(args=args, **kwargs)
+            result = _orig_cmd_main(args=args, **kwargs)
+            # Click standalone_mode=False returns the exit code for explicit Exit.
+            if isinstance(result, int) and not isinstance(result, bool):
+                scope.outcome = exit_outcome(result, scope)
+            return result
         except SystemExit as exc:
-            # Click uses SystemExit(0) even after successful CLI/MCP calls.
-            # Preserve its exit while recording the outcome, not the exception.
-            success = exc.code is None or exc.code == 0
-            if not success:
-                error_kind = type(exc).__name__
+            scope.outcome = exit_outcome(exc.code, scope)
+            import click
+            cause = exc.__context__
+            seen = set()
+            while cause is not None and id(cause) not in seen:
+                seen.add(id(cause))
+                if isinstance(cause, KeyboardInterrupt):
+                    scope.outcome = "cancelled"
+                    error_kind = "KeyboardInterrupt"
+                    break
+                if isinstance(cause, click.ClickException) and scope.outcome == "unknown_error":
+                    scope.outcome = "expected_error"
+                cause = cause.__context__
+            if scope.outcome in {"expected_error", "unknown_error"}:
+                error_kind = "SystemExit"
             raise
         except BaseException as exc:
-            success = False
+            import click
+            scope.outcome = ("cancelled" if isinstance(exc, (KeyboardInterrupt, click.Abort))
+                             else "expected_error" if isinstance(exc, click.ClickException)
+                             else "internal_error")
             error_kind = type(exc).__name__
             raise
         finally:
             try:
-                from sourcecode import telemetry as _tel
+                ok = scope.outcome in {"succeeded", "negative"}
                 _tel.record(
-                    "execution_completed",
-                    cmd=("mcp" if command == "mcp" else "telemetry" if command == "telemetry" else "analyze"),
-                    command=command,
-                    flags=_telemetry_flags(args),
-                    duration_s=time.monotonic() - started,
-                    success=success,
-                    error_kind=error_kind,
+                    "execution_completed" if ok else "execution_failed",
+                    **fields, duration_s=time.monotonic() - started,
+                    success=ok, outcome=scope.outcome, error_kind=error_kind,
                 )
             except Exception:
                 pass
+            if parent and scope.outcome != "succeeded":
+                parent.outcome = scope.outcome
+            current.reset(token)
             if _previous_invocation is None:
                 _tls.__dict__.pop("invocation_args", None)
             else:
@@ -13631,6 +13654,9 @@ def verify_edit_cmd(
     output = _serialize_dict(v.to_dict(), format)
     _emit_command_output(output, output_path, copy,
                          success_msg=f"verify-edit verdict written to {output_path}")
+    if v.exit_code != 0:
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative" if v.exit_code == 1 else "expected_error")
     if ci and v.exit_code != 0:
         raise typer.Exit(code=v.exit_code)
 
@@ -13974,6 +14000,9 @@ def verify_cmd(
         copy,
         success_msg=f"verify report written to {output_path}",
     )
+    if report.exit_code != 0:
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative" if report.exit_code == 1 else "expected_error")
     if ci and report.exit_code != 0:
         raise typer.Exit(code=report.exit_code)
 
@@ -14795,6 +14824,8 @@ def audit_verify_cmd(
         success_msg="audit signature verified" if verdict["valid"] else "audit signature mismatch",
     )
     if not verdict["valid"]:
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative")
         raise typer.Exit(code=1)
 
 
@@ -15186,6 +15217,8 @@ def migrate_apply_cmd(
             ),
         )
         if ci and data["gate"]["exit_code"]:
+            from sourcecode.telemetry.lifecycle import mark
+            mark("negative")
             raise typer.Exit(code=1)
         return
 
@@ -16233,6 +16266,9 @@ def migrate_check_cmd(
     )
     if ci:
         _gate = (payload or report.to_dict()).get("metadata", {}).get("gate", {})
+        if _gate.get("exit_code", 0):
+            from sourcecode.telemetry.lifecycle import mark
+            mark("negative")
         raise typer.Exit(code=int(_gate.get("exit_code", 0)))
 
 
@@ -16749,6 +16785,8 @@ def pr_impact_cmd(
         # UNKNOWN means the analysis could not see everything it was asked about.
         # A gate must not read that as "below threshold".
         if report.risk_level == "UNKNOWN" or _actual >= _threshold:
+            from sourcecode.telemetry.lifecycle import mark
+            mark("negative")
             raise typer.Exit(code=1)
 
 
@@ -17862,8 +17900,12 @@ def self_audit_cmd(
     )
 
     if fail_on == "fail" and data["verdict"] == "fail":
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative")
         raise typer.Exit(code=1)
     if fail_on == "unknown" and data["verdict"] in ("fail", "unknown"):
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative")
         raise typer.Exit(code=1)
 
 
@@ -18003,8 +18045,12 @@ def drift_cmd(
         + data["counts"]["added_without_a_matching_rule"]
     )
     if fail_on_exposure and _exposed:
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative")
         raise typer.Exit(code=1)
     if fail_on_drift and data["drifted"]:
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative")
         raise typer.Exit(code=1)
 
 
@@ -18274,10 +18320,16 @@ def pr_risk_cmd(
         # that nobody could answer the question, and a gate that passes on that
         # is a gate that passes on a blind spot.
         if result.verdict == VERDICT_UNKNOWN:
+            from sourcecode.telemetry.lifecycle import mark
+            mark("negative")
             raise typer.Exit(code=1)
         if fail_on == "block" and result.verdict == VERDICT_BLOCK:
+            from sourcecode.telemetry.lifecycle import mark
+            mark("negative")
             raise typer.Exit(code=1)
         if fail_on == "review" and result.verdict in (VERDICT_BLOCK, VERDICT_REVIEW):
+            from sourcecode.telemetry.lifecycle import mark
+            mark("negative")
             raise typer.Exit(code=1)
 
 
@@ -18691,8 +18743,12 @@ def cve_cmd(
     )
 
     if fail_on == "reachable" and _reachable > 0:
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative")
         raise typer.Exit(code=1)
     if fail_on == "any" and _affected_total > 0:
+        from sourcecode.telemetry.lifecycle import mark
+        mark("negative")
         raise typer.Exit(code=1)
 
 
@@ -19265,6 +19321,8 @@ def version_cmd(
     """
     from sourcecode.release_info import advisory_line, build_status
     from sourcecode.product_info import COPYRIGHT, PRODUCT, TAGLINE, build_provenance
+    from sourcecode.update import check as check_for_update
+    _update_status = check_for_update()
 
     if getattr(sys.stdout, "isatty", lambda: False)():
         _lines = [f"{PRODUCT} {__version__}", TAGLINE, COPYRIGHT]
@@ -19274,11 +19332,13 @@ def version_cmd(
         _advisory = advisory_line()
         if _advisory:
             _lines.append(_advisory)
+        if _update_status.get("status") == "available":
+            _lines.append(f"A newer ASK version is available: {_update_status['latest_version']} (run `ask update`)")
         _emit_text_output("\n".join(_lines), copy, output_path)
     else:
         import json as _json_ver
         from sourcecode.envelope import ENVELOPE_VERSION, available_schemas
-        _emit_text_output(_json_ver.dumps({
+        _version_payload = {
             "cli_version": __version__,
             "mcp_schema_version": __version__,
             "compatibility_schema_version": "1.0",
@@ -19295,7 +19355,10 @@ def version_cmd(
             # about what this release publishes.
             "registries": published_registries(),
             "provenance": build_provenance(),
-        }, ensure_ascii=_json_ensure_ascii()), copy, output_path)
+        }
+        if _update_status.get("status") == "available":
+            _version_payload["update_available"] = _update_status["latest_version"]
+        _emit_text_output(_json_ver.dumps(_version_payload, ensure_ascii=_json_ensure_ascii()), copy, output_path)
 
 
 def published_registries() -> "list[str]":
@@ -19485,6 +19548,41 @@ def schema_cmd(
     )
 
 
+# ── update / config ───────────────────────────────────────────────────────────
+
+@app.command("update")
+def update_cmd(
+    check_only: bool = typer.Option(False, "--check", help="Check PyPI without installing."),
+    yes: bool = typer.Option(False, "--yes", help="Confirm installation without prompting."),
+    force: bool = typer.Option(False, "--force", help="Ignore the 24-hour check cache."),
+) -> None:
+    """Check for a newer ASK release and optionally install it."""
+    from sourcecode.update import check, install
+    result = check(force=force)
+    if result.get("status") == "available" and not check_only:
+        target = result["latest_version"]
+        if not yes:
+            if not sys.stdin.isatty() or not sys.stderr.isatty():
+                _emit_error_json(INVALID_INPUT_CODE, "Updating requires confirmation.", hint="Run `ask update --yes` explicitly in automation.")
+                raise typer.Exit(code=2)
+            if not typer.confirm(f"ASK {target} is available. Install it now?", err=True):
+                result = {**result, "status": "declined"}
+            else:
+                result = install(target)
+        else:
+            result = install(target)
+    if result.get("status") == "available":
+        message = f"ASK {result['latest_version']} is available (current: {result['current_version']}). Run `ask update` to install."
+    elif result.get("status") == "current":
+        message = f"ASK is up to date ({result['current_version']})."
+    elif result.get("status") == "declined":
+        message = "Update declined; ASK was not changed."
+    elif result.get("status") == "updated":
+        message = f"ASK updated to {result.get('target_version')}. Restart persistent MCP processes."
+    else:
+        message = f"ASK update status: {result.get('status')} ({result.get('reason', 'no additional details')})."
+    _emit_command_output(json.dumps({**result, "message": message}, ensure_ascii=False), None, False, fmt="json")
+
 # ── config ────────────────────────────────────────────────────────────────────
 
 @app.command("config")

sourcecode/license.py

@@ -718,6 +718,7 @@ def activate_license(license_key: str) -> None:
     Outputs JSON to stdout on success; exits 0 on success, 1 on any failure.
     Errors use the CLI JSON envelope on stderr so stdout remains machine-safe.
     """
+    _emit_telemetry("activation_started", feature="key", outcome="started")
     if not _LICENSE_KEY_RE.match(license_key):
         _fail("invalid_license", "License key format is invalid.")
 

sourcecode/mcp/runner.py

@@ -48,8 +48,16 @@ def run_command(args: list[str]) -> Any:
     # Pass raw args to invoke — the _cmd_main hook inside cli.py handles path
     # extraction via _preprocess_args. Pre-processing here would strip the path
     # from args, then _cmd_main would re-process the stripped list and lose it.
-    with _runner_lock:
-        result = _runner.invoke(app, list(args))
+    from sourcecode.telemetry.lifecycle import Execution, current
+    token = None
+    if current.get() is None:
+        token = current.set(Execution(interface="mcp", id=""))
+    try:
+        with _runner_lock:
+            result = _runner.invoke(app, list(args))
+    finally:
+        if token is not None:
+            current.reset(token)
 
     if result.exit_code != 0:
         stdout_raw = getattr(result, "output", "")

sourcecode/mcp/server.py

@@ -63,13 +63,17 @@ def _record_tool_invocation(name: Any, success: bool, started: float) -> None:
         import time as _time
 
         from sourcecode import telemetry as _tel
+        from sourcecode.telemetry.lifecycle import current
+        scope = current.get()
 
         _tel.record(
             "mcp_tool_invoked",
             cmd="mcp",
             tool=str(name) if name else None,
             duration_s=_time.monotonic() - started,
-            success=success,
+            success=success or bool(scope and scope.outcome == "negative"),
+            outcome=(scope.outcome if scope and scope.outcome != "succeeded"
+                     else "succeeded" if success else "expected_error"),
         )
     except Exception:
         pass  # telemetry must never affect a tool call
@@ -113,6 +117,8 @@ try:
                 }
                 _record_tool_invocation(self.name, False, _started)
                 return _payload
+            from sourcecode.telemetry.lifecycle import mark
+            mark("internal_error")
             _record_tool_invocation(self.name, False, _started)
             raise
         _record_tool_invocation(
@@ -120,7 +126,28 @@ try:
         )
         return _result
 
-    _FastMCPTool.run = _patched_tool_run  # type: ignore[method-assign]
+    _dispatch_with_telemetry = _patched_tool_run
+
+    async def _scoped_tool_run(self, arguments, context=None, convert_result=False):
+        from sourcecode import telemetry as tel
+        from sourcecode.telemetry.lifecycle import Execution, current
+        scope = Execution(interface="mcp")
+        token = current.set(scope)
+        started = _time_mod.monotonic()
+        tel.record("execution_started", cmd="mcp", tool=self.name, outcome="started")
+        try:
+            return await _dispatch_with_telemetry(self, arguments, context, convert_result)
+        except BaseException as exc:
+            import asyncio
+            if isinstance(exc, (KeyboardInterrupt, asyncio.CancelledError)):
+                tel.record("mcp_tool_invoked", cmd="mcp", tool=self.name,
+                           success=False, outcome="cancelled",
+                           duration_s=_time_mod.monotonic() - started)
+            raise
+        finally:
+            current.reset(token)
+
+    _FastMCPTool.run = _scoped_tool_run  # type: ignore[method-assign]
 except Exception:
     pass  # never break server startup over a patch failure
 
@@ -1678,6 +1705,24 @@ def version() -> dict:
     return _execute(["version"])
 
 
+@mcp.tool()
+def check_for_updates(force: bool = False) -> dict:
+    """Check PyPI for a newer ASK release without installing anything."""
+    from sourcecode.update import check
+    return {"success": True, "data": check(force=force), "error": None}
+
+
+@mcp.tool()
+def update_ask(confirm: bool = False, force: bool = False) -> dict:
+    """Check ASK's PyPI release; install only when confirm=true."""
+    from sourcecode.update import check, install
+    status = check(force=force)
+    if not confirm or status.get("status") != "available":
+        return {"success": True, "data": {**status, "installed": False}, "error": None}
+    result = install(status["latest_version"])
+    return {"success": result.get("status") in {"updated", "current"}, "data": {**result, "installed": result.get("status") == "updated"}, "error": None if result.get("status") in {"updated", "current"} else result}
+
+
 @mcp.tool()
 def config() -> dict:
     """Show sourcecode CLI configuration.

sourcecode/telemetry/__init__.py

@@ -14,12 +14,13 @@ See docs/privacy.md for full details.
 
 from __future__ import annotations
 
+import os
 import platform
 import sys
 import uuid
 from typing import Any, Optional
 
-from sourcecode.telemetry.config import get_install_id, is_enabled
+from sourcecode.telemetry.config import get_install_id, is_enabled, telemetry_context
 from sourcecode.telemetry.events import (
     TelemetryEvent,
     duration_bucket,
@@ -30,10 +31,14 @@ from sourcecode.telemetry.transport import send
 
 # Ephemeral session identifier — new random value each process start.
 # 8 hex chars, never persisted, used only to correlate events within one run.
-_SESSION: str = uuid.uuid4().hex[:8]
+_SESSION: str = uuid.uuid4().hex
+_SESSION_PID = os.getpid()
 
 
 def session_id() -> str:
+    global _SESSION, _SESSION_PID
+    if os.getpid() != _SESSION_PID:
+        _SESSION, _SESSION_PID = uuid.uuid4().hex, os.getpid()
     return _SESSION
 
 
@@ -81,6 +86,9 @@ def record(
     feature: Optional[str] = None,
     tool: Optional[str] = None,
     repo_size: Optional[str] = None,
+    outcome: Optional[str] = None,
+    execution_id: str = "",
+    parent_execution_id: str = "",
 ) -> None:
     """Record a telemetry event. Fire-and-forget — never blocks or raises.
 
@@ -91,7 +99,17 @@ def record(
         return
 
     try:
+        from sourcecode.telemetry.lifecycle import current
+        scope = current.get()
+        install = get_install_id()
+        if not install:
+            return
         ev = TelemetryEvent(
+            telemetry_context=telemetry_context(),
+            interface="mcp" if cmd == "mcp" or (scope and scope.interface == "mcp") else "cli",
+            outcome=outcome or ("succeeded" if success else "expected_error"),
+            execution_id=execution_id or (scope.id if scope else str(uuid.uuid4())),
+            parent_execution_id=parent_execution_id or (scope.parent if scope else ""),
             event=event,
             v=_sourcecode_version(),
             py=_python_version(),
@@ -111,11 +129,12 @@ def record(
             error_kind=error_kind,
             feature=feature,
             tool=tool,
-            install=get_install_id(),
-            session=_SESSION,
+            install=install,
+            session=session_id(),
         )
         payload = sanitize(ev)
-        send(payload)
+        if payload.get("install"):
+            send(payload)
     except Exception:
         pass  # telemetry must never affect the main process
 

sourcecode/telemetry/config.py

@@ -17,6 +17,9 @@ from __future__ import annotations
 
 import json
 import os
+import sys
+import tempfile
+import uuid
 from pathlib import Path
 from typing import Any
 
@@ -59,6 +62,8 @@ def is_enabled() -> bool:
       3. config file 'enabled' flag, if the user has made an explicit choice
       4. default: True
     """
+    if telemetry_context() != "production":
+        return False
     env = os.environ.get(_ENV_VAR, "").strip()
     if env == "0":
         return False
@@ -92,27 +97,58 @@ def mark_asked() -> None:
     _save(data)
 
 
+def telemetry_context() -> str:
+    """Origin evidence only; never infer automation from MCP or usage volume."""
+    if "pytest" in sys.modules or os.environ.get("PYTEST_CURRENT_TEST"):
+        return "test"
+    if any(os.environ.get(k, "").lower() not in ("", "0", "false") for k in
+           ("CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "TF_BUILD", "JENKINS_URL", "BUILDKITE", "CIRCLECI", "TRAVIS", "TEAMCITY_VERSION", "DRONE", "SEMAPHORE")):
+        return "ci"
+    explicit = os.environ.get("SOURCECODE_TELEMETRY_CONTEXT", "")
+    if explicit in {"test", "ci", "development"}:
+        return explicit
+    # An editable source checkout is development, irrespective of working directory.
+    if (Path(__file__).resolve().parents[3] / ".git").exists():
+        return "development"
+    return "production"
+
+
 def get_install_id() -> str:
-    """Stable anonymous install id — a random UUID v4.
+    """One random UUID per persistent config directory, shared across versions.
 
-    Created lazily on first enabled event. NOT derived from hardware, email,
-    hostname or any identifier — it only says "the same install across runs",
-    which is what enables unique-user, conversion and retention metrics.
-    Returns "" if it cannot be persisted (telemetry then degrades to events
-    without a stable id, never an error).
+    A complete temporary file is published with an atomic, no-replace hard link.
+    Competing processes read the winner; settings writes cannot rotate identity.
+    Preserve a valid legacy JSON UUID. On unavailable storage, suppress telemetry.
     """
-    data = _load()
-    tel = data.setdefault("telemetry", {})
-    iid = tel.get("install_id")
-    if not iid:
-        import uuid
-        iid = str(uuid.uuid4())
-        tel["install_id"] = iid
-        _save(data)
-        # If the write failed, re-read to avoid handing out a non-persisted id
-        if not _load().get("telemetry", {}).get("install_id"):
-            return ""
-    return str(iid)
+    identity = _CONFIG_FILE.with_name("install-id")
+    temporary = None
+    try:
+        if identity.exists():
+            return str(uuid.UUID(identity.read_text(encoding="ascii").strip()))
+        legacy = _load().get("telemetry", {}).get("install_id")
+        try:
+            candidate = str(uuid.UUID(legacy)) if legacy else str(uuid.uuid4())
+        except (ValueError, TypeError, AttributeError):
+            candidate = str(uuid.uuid4())
+        identity.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(prefix=".install-", dir=identity.parent)
+        with os.fdopen(fd, "w", encoding="ascii") as stream:
+            stream.write(candidate)
+            stream.flush()
+            os.fsync(stream.fileno())
+        try:
+            os.link(temporary, identity)
+        except FileExistsError:
+            pass
+        return str(uuid.UUID(identity.read_text(encoding="ascii").strip()))
+    except (OSError, ValueError, TypeError, AttributeError):
+        return ""
+    finally:
+        if temporary:
+            try:
+                os.unlink(temporary)
+            except OSError:
+                pass
 
 
 def config_file_path() -> Path:

sourcecode/telemetry/events.py

@@ -69,6 +69,12 @@ class TelemetryEvent:
     """
 
     event: str
+    schema_version: int = 2
+    telemetry_context: str = "production"
+    interface: str = "cli"
+    outcome: str = "succeeded"
+    execution_id: str = ""
+    parent_execution_id: str = ""
     ts: str = field(default_factory=_now_utc)
     v: str = ""
     py: str = ""

sourcecode/telemetry/filters.py

@@ -64,16 +64,18 @@ _SAFE_COMMANDS: frozenset[str] = frozenset({
     "audit-report", "migrate-recipe", "data-exposure", "posture", "migrate-check", "impact-chain",
     "pr-impact", "explain", "onboard", "review-pr", "fix-bug", "modernize", "rename-class",
     "chunk-file", "activate", "selftest", "explain-endpoint", "regress", "version", "schema",
-    "config", "archetype", "cold-start",
+    "config", "archetype", "cold-start", "pack", "audit-verify",
 })
 _SAFE_EVENTS: frozenset[str] = frozenset({
     "command_executed",
+    "execution_started",
     "execution_completed",
     "execution_failed",
     "telemetry_enabled",
     "telemetry_disabled",
     "gate_blocked",
     "activation",
+    "activation_started",
     "mcp_tool_invoked",
 })
 # Closed set of gated features / task names. Used to learn which capability
@@ -112,7 +114,7 @@ def _safe_error_kind(value: str | None) -> str | None:
     if not value:
         return None
     # Exception class names are CamelCase identifiers, no spaces, no paths
-    name = value.split(":")[-1].strip()  # strip message after ':'
+    name = value.split(":", 1)[0].strip()  # strip message after ':'
     name = name.split(".")[-1].strip()   # strip module prefix
     if len(name) > 64 or _SPACE_PATTERN.search(name) or _PATH_PATTERN.search(name):
         return "UnknownError"
@@ -135,7 +137,7 @@ def _safe_tool(value: str | None) -> str | None:
 
 def _safe_session(value: str) -> str:
     """Session ID must be a short hex string only."""
-    if re.match(r"^[0-9a-f]{1,16}$", value):
+    if re.match(r"^[0-9a-f]{1,32}$", value):
         return value
     return ""
 
@@ -155,6 +157,14 @@ def sanitize(event: TelemetryEvent) -> dict[str, Any]:
     If any field cannot be validated as safe, it is replaced with a safe default.
     """
     safe: dict[str, Any] = {
+        "domain": "licensing" if event.event in {"activation", "activation_started", "gate_blocked"} or event.command in {"activate", "auth"} else "execution",
+        "schema_version": 2,
+        "telemetry_context": _safe_str(event.telemetry_context, frozenset({"production", "development", "test", "ci"}), "unknown"),
+        "interface": _safe_str(event.interface, frozenset({"cli", "mcp"}), "unknown"),
+        "outcome": _safe_str(event.outcome, frozenset({"started", "succeeded", "negative", "expected_error", "internal_error", "unknown_error", "cancelled"}), "unknown"),
+        "execution_id": _safe_install(event.execution_id),
+        "parent_execution_id": _safe_install(event.parent_execution_id),
+        "capabilities": sorted({name for flag, name in {"--since": "incremental", "--compact": "compact", "--git-context": "git_context", "--agent": "agent"}.items() if flag in event.flags}),
         "event": _safe_str(event.event, _SAFE_EVENTS, "command_executed"),
         "ts": event.ts[:20] if event.ts else "",  # truncate to date+time, no sub-second
         "v": event.v[:16] if event.v else "",
@@ -167,7 +177,7 @@ def sanitize(event: TelemetryEvent) -> dict[str, Any]:
         "output_fmt": _safe_str(event.output_fmt, _SAFE_FMTS, "json"),
         "repo_size": _safe_str(event.repo_size, _SAFE_SIZES, "unknown"),
         "duration": _safe_str(event.duration, _SAFE_DURATIONS, "unknown"),
-        "success": bool(event.success),
+        "success": None if event.outcome == "started" else event.outcome in {"succeeded", "negative"},
     }
 
     if event.error_kind:

sourcecode/telemetry/lifecycle.py

@@ -0,0 +1,30 @@
+"""Execution correlation; context local to a CLI invocation or async MCP call."""
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+import uuid
+
+
+@dataclass
+class Execution:
+    interface: str = "cli"
+    parent: str = ""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    outcome: str = "succeeded"
+    command: str = "unknown"
+
+
+current: ContextVar[Execution | None] = ContextVar("telemetry_execution", default=None)
+
+
+def mark(outcome: str) -> None:
+    scope = current.get()
+    if scope is not None:
+        scope.outcome = outcome
+
+
+def exit_outcome(code: object, scope: Execution) -> str:
+    if scope.outcome != "succeeded":
+        return scope.outcome
+    return "succeeded" if code is None or code == 0 else "unknown_error"

sourcecode/telemetry/transport.py

@@ -10,11 +10,29 @@ Design principles:
 
 from __future__ import annotations
 
+import atexit
+import time
 import json
 import os
 import threading
 from typing import Any
 
+from sourcecode.telemetry.config import telemetry_context
+
+_pending: set[threading.Thread] = set()
+_lock = threading.Lock()
+
+def flush(timeout: float = 0.3) -> None:
+    """Best-effort bounded process-exit drain; never claim reliable delivery."""
+    deadline = time.monotonic() + timeout
+    with _lock:
+        pending = list(_pending)
+    for thread in pending:
+        thread.join(max(0, deadline - time.monotonic()))
+
+
+atexit.register(flush)
+
 _DEFAULT_ENDPOINT = "https://qkndlmyekvujjdgthtmz.supabase.co/functions/v1/telemetry"
 _TIMEOUT_S = 3
 
@@ -28,6 +46,8 @@ def _endpoint() -> str:
 
 def _send_blocking(payload: dict[str, Any]) -> None:
     """Blocking send — runs inside a daemon thread only."""
+    if telemetry_context() != "production":
+        return
     try:
         import urllib.request
 
@@ -41,7 +61,8 @@ def _send_blocking(payload: dict[str, Any]) -> None:
             },
             method="POST",
         )
-        urllib.request.urlopen(req, timeout=_TIMEOUT_S)
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S):
+            pass
     except Exception:
         pass  # always silent — a missed event is not an error
 
@@ -51,5 +72,19 @@ def send(payload: dict[str, Any]) -> None:
 
     Returns immediately. The main process can exit without waiting.
     """
-    t = threading.Thread(target=_send_blocking, args=(payload,), daemon=True)
-    t.start()
+    if telemetry_context() != "production":
+        return
+
+    def deliver() -> None:
+        try:
+            _send_blocking(payload)
+        finally:
+            with _lock:
+                _pending.discard(threading.current_thread())
+
+    with _lock:
+        if len(_pending) >= 64:
+            return
+        t = threading.Thread(target=deliver, daemon=True)
+        _pending.add(t)
+        t.start()

sourcecode/update.py

@@ -0,0 +1,155 @@
+"""Safe, explicit ASK update checks and installation."""
+from __future__ import annotations
+
+import json
+import os
+import random
+from pathlib import Path
+import re
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+PYPI_URL = "https://pypi.org/pypi/sourcecode/json"
+_CACHE_TTL = 24 * 60 * 60
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$")
+
+
+def _version_tuple(value: str) -> tuple[int, int, int] | None:
+    match = _VERSION_RE.match(value.strip())
+    return tuple(int(part) for part in match.groups()[:3]) if match else None
+
+
+def _cache_path() -> Path:
+    override = os.environ.get("SOURCECODE_UPDATE_CACHE")
+    return Path(override).expanduser() if override else Path.home() / ".cache" / "sourcecode" / "update-check.json"
+
+
+def _runtime_allowed() -> bool:
+    from sourcecode.telemetry.config import telemetry_context
+    return telemetry_context() == "production" and os.environ.get("SOURCECODE_UPDATE_DISABLED") not in {"1", "true", "yes"}
+
+
+def _lock_path() -> Path:
+    return _cache_path().with_name("update.lock")
+
+
+def _acquire_lock(timeout: float = 2.0) -> int | None:
+    try:
+        _lock_path().parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return None
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            return os.open(_lock_path(), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except FileExistsError:
+            time.sleep(0.03 + random.random() * 0.04)
+        except OSError:
+            return None
+    return None
+
+
+def _release_lock(fd: int | None) -> None:
+    if fd is None:
+        return
+    try:
+        os.close(fd)
+        _lock_path().unlink()
+    except OSError:
+        pass
+
+
+def _read_cache() -> dict[str, Any] | None:
+    try:
+        data = json.loads(_cache_path().read_text(encoding="utf-8"))
+        if time.time() - float(data.get("checked_at", 0)) < _CACHE_TTL:
+            return data
+    except (OSError, ValueError, TypeError):
+        pass
+    return None
+
+
+def _write_cache(data: dict[str, Any]) -> None:
+    try:
+        path = _cache_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_suffix(".tmp")
+        temporary.write_text(json.dumps(data), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        pass
+
+
+def current_version() -> str:
+    from sourcecode import __version__
+    return str(__version__)
+
+
+def check(*, force: bool = False) -> dict[str, Any]:
+    """Return update status without raising or installing."""
+    current = current_version()
+    if not _runtime_allowed():
+        return {"status": "suppressed", "current_version": current, "reason": "non-production runtime"}
+    if not force:
+        cached = _read_cache()
+        if cached:
+            cached["cached"] = True
+            return cached
+    request = urllib.request.Request(PYPI_URL, headers={"Accept": "application/json", "User-Agent": f"sourcecode/{current}"})
+    try:
+        with urllib.request.urlopen(request, timeout=3) as response:
+            payload = json.loads(response.read(256 * 1024).decode("utf-8"))
+        latest = str(payload["info"]["version"])
+        if _version_tuple(latest) is None:
+            raise ValueError("invalid version from PyPI")
+        status = "available" if _version_tuple(latest) > _version_tuple(current) else "current"
+        result = {"status": status, "current_version": current, "latest_version": latest, "checked_at": time.time(), "source": "pypi"}
+        _write_cache(result)
+        return result
+    except (OSError, ValueError, KeyError, TypeError, json.JSONDecodeError) as exc:
+        return {"status": "unavailable", "current_version": current, "reason": type(exc).__name__}
+
+
+def install(target: str | None = None) -> dict[str, Any]:
+    """Install the latest package through the running interpreter's pip."""
+    if not _runtime_allowed():
+        return {"status": "suppressed", "reason": "non-production runtime", "current_version": current_version()}
+    previous = current_version()
+    status = check()
+    latest = target or status.get("latest_version")
+    if status.get("status") != "available" or not latest:
+        return {**status, "status": "current" if status.get("status") == "current" else status.get("status", "unavailable")}
+    target_tuple = _version_tuple(str(latest))
+    if target_tuple is None:
+        return {"status": "failed", "target_version": latest, "reason": "invalid_target_version"}
+    fd = _acquire_lock()
+    if fd is None:
+        return {"status": "busy", "target_version": latest, "reason": "another_update_in_progress"}
+    command = [sys.executable, "-m", "pip", "install", "--upgrade", "--disable-pip-version-check", "sourcecode"]
+    try:
+        result = subprocess.run(command, check=False, capture_output=True, text=True, timeout=120)
+    except (OSError, subprocess.SubprocessError) as exc:
+        result = None
+        failure = type(exc).__name__
+    else:
+        failure = "pip_exit" if result.returncode != 0 else None
+    try:
+        if failure:
+            rollback = subprocess.run([sys.executable, "-m", "pip", "install", "--disable-pip-version-check", f"sourcecode=={previous}"], check=False, capture_output=True, text=True, timeout=120)
+            return {"status": "failed", "target_version": latest, "reason": failure, "exit_code": getattr(result, "returncode", None), "rollback": "restored" if rollback.returncode == 0 else "failed"}
+        try:
+            from importlib.metadata import version as installed_version
+            observed = installed_version("sourcecode")
+        except Exception:
+            observed = ""
+        observed_tuple = _version_tuple(observed)
+        if observed_tuple is None or observed_tuple < target_tuple:
+            rollback = subprocess.run([sys.executable, "-m", "pip", "install", "--disable-pip-version-check", f"sourcecode=={previous}"], check=False, capture_output=True, text=True, timeout=120)
+            return {"status": "failed", "target_version": latest, "previous_version": previous, "loaded_version": observed, "reason": "installed_version_mismatch", "rollback": "restored" if rollback.returncode == 0 else "failed"}
+        return {"status": "updated", "previous_version": previous, "target_version": latest, "installed_version": observed, "restart_required": True}
+    finally:
+        _release_lock(fd)

{sourcecode-5.9.31.dist-info → sourcecode-5.9.32.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.9.31
+Version: 5.9.32
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.31-blue)
+![Version](https://img.shields.io/badge/version-5.9.32-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -290,7 +290,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.31 — and, on a build that has aged,
+ask version                    # ask 5.9.32 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.9.31.dist-info → sourcecode-5.9.32.dist-info}/RECORD

@@ -1,6 +1,6 @@
-sourcecode/__init__.py,sha256=aE6bZn3549jPrAPXdSSzOOUcSbTElZNwvDgnf8PkQRw,309
+sourcecode/__init__.py,sha256=ncGdSArOW-Az9AQcz2GdsqINaoj8Lgl5TWfe6oqyjzc,309
 sourcecode/__main__.py,sha256=qDFVkobwsdZrX0B3stiRqsUNivVpybKO-egzAwCW4xw,165
-sourcecode/_build_commit.py,sha256=soR9bluaRLiRQOZKiKG6JgH8eSuPbG1Am0XOse7hd9s,12816
+sourcecode/_build_commit.py,sha256=9ZnAT__s9q1eWX_Ez3hNstlJg_IEgCuX1j4sV4TBADk,12816
 sourcecode/access_drift.py,sha256=uYD8ipiEAaTnkz0IhG6ujU_KI3LghdY-6ycurs-BZnc,9355
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/analysis_budget.py,sha256=ZuNEboPF8A6GK-_V7WNt92ezgriga7_Rbr-vvSN4UEE,4183
@@ -35,7 +35,7 @@ sourcecode/change_plan.py,sha256=drAoDsqFplutCLc6Y0xue7sYkTls0SpYh7aOXvttv3I,129
 sourcecode/ci_output.py,sha256=X4NRokWWMRF9Ex8OQrEO2g04GzJ00GDP5zYIoqI9YCc,4625
 sourcecode/cir_graphs.py,sha256=RytqSv1WF8kdlfXj2fPQz16LY4akS2kyThbdWL8beCQ,14835
 sourcecode/classifier.py,sha256=ft1RGPIChvO84q2QMrEH93x1J15AXNWMh26lnxvoRao,26476
-sourcecode/cli.py,sha256=XII7rmrcJA-eN-sMlfLCKP7fUNl83iEXQfP_-Okdyy8,988561
+sourcecode/cli.py,sha256=5NIrvizSSIb966DIpoELNqy_nVO94B5QMSKMGfupfj4,994167
 sourcecode/click_runtime.py,sha256=K2cUdzFhbd6uEUpucWptXE89_z-ZNZGsqgd-34usUXk,1890
 sourcecode/client_calls.py,sha256=YOPnfRZzRyqmdHvXSVeiunW8cuiuCuWXacNIQRgKMCw,22640
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
@@ -101,7 +101,7 @@ sourcecode/integration_coordinates.py,sha256=rvuApnS7WdRUbeQLg_oKj-Gi0koO2RKdw6H
 sourcecode/intent_router.py,sha256=hC_o0VYfSjzSXecFkpiD7vzFgvt44YAw6E_jrMeGiZ4,15555
 sourcecode/jdk_exports.py,sha256=fCrlwNAXUT9gge_joq6kMnY3zJxYB2pxqy-0w3o3MJI,874
 sourcecode/jvm_inventory.py,sha256=06mlOWSwfs9jBk4lGkCSZHRbapOG41dQ5gopvOVf7dE,14182
-sourcecode/license.py,sha256=eIEuIVQXywl_S9LOIACOEpJ4M5RyaPvWrqg_jSNOrXA,31088
+sourcecode/license.py,sha256=HJ-RBnh7hRIhzoABr-gGstgdbsRVmv_lg5Vh_aZK0oA,31164
 sourcecode/manifest_cache.py,sha256=mhCgOYNQgn1VIQ2HUY57Dmer1AIF-1suR0XddnI9M2g,4381
 sourcecode/mcp_nudge.py,sha256=beNjfyb7z09T1rnS4t6Q4qfbLzZQNaP6ddCA4XpmV0s,3256
 sourcecode/metrics_analyzer.py,sha256=gLoRWKygF18jLgwsqmGXSWopw-f5iO1VbM7Jjdif6ag,22809
@@ -200,6 +200,7 @@ sourcecode/timeline_cache.py,sha256=99RQ-MW3wqxjtuHcVB_k83USsxWP6DqzeupfSzKR_CE,
 sourcecode/token_estimate.py,sha256=_2cworfPkfP2ZxVcwX_Ltu0vFdMvK-FMuTY3qJAqI5M,9415
 sourcecode/tree_utils.py,sha256=oAwkGyrixO2VMX4ZMIDzg9V2oBxt3KIxFN3ahVMxKJo,2174
 sourcecode/type_usage_surface.py,sha256=51IrKRQoIoRnlsiDjHnqpJBn2rc6E59aRhgS0HTzAF0,4428
+sourcecode/update.py,sha256=D562zph5vPm7FTVjeBeF6xtZwy4ByT31SN6A-Uumk44,6440
 sourcecode/validation_inference.py,sha256=-oWJqE6PqkqcZbCFDJeWCQHgI9Dbuv5ggJWD3LE_2IU,20817
 sourcecode/validation_surface.py,sha256=LeoOeZfTZmz5l4f2EDXNlOlzoTlL3EMVrYY8HEKGEg0,36716
 sourcecode/verify_edit.py,sha256=Ha0JNsC6CYHjtbetVZurLetqBNjriykYJ8ITDUMuNVY,63479
@@ -240,8 +241,8 @@ sourcecode/mcp/__init__.py,sha256=XU4HfRGbdid8wdUA0x_4f7uKZD1z3mv_XUY_WU_T9Mw,17
 sourcecode/mcp/dependency_import.py,sha256=wfvw1rmDE3n2mHDj-yHnCuy9HZ7TtPqsHG2BU-Scl1k,4146
 sourcecode/mcp/orchestrator.py,sha256=RUzx2uRfwk-rnEy1RKeXjTBPfUaQiBldo-b2FryL6yI,36826
 sourcecode/mcp/registry.py,sha256=xewjyZDr2A8Fdu1SUOT1QXJ86mww-pbqL4EFpXuRklo,69393
-sourcecode/mcp/runner.py,sha256=dRvI0xS2wa8DH0diYjJiAoaGeVdtf389PekWwwh8wRI,3083
-sourcecode/mcp/server.py,sha256=L3xxLaG-bLe3Asr4ZESiEIYldhvKHkfpCMoucndvLvY,76070
+sourcecode/mcp/runner.py,sha256=5cvdsR04EWg9HTo8SNIytJA-OVE01nUYZUO-3ZbItb0,3352
+sourcecode/mcp/server.py,sha256=uzRLjOHZR_fm1ZxhINcljG8_YvuI37KD1l5p_y_ZnjQ,78323
 sourcecode/mcp/onboarding/__init__.py,sha256=sj2PWqEBmMc4zBNkomg89WtL0M6S7A9yb7_wAuSWNP4,66
 sourcecode/mcp/onboarding/applier.py,sha256=Sx9vHTaXr_M1Bs4uMjO7qa_a2_p4J9oz93oJsKQ7ds4,3298
 sourcecode/mcp/onboarding/backup.py,sha256=ihqGOR8QTX8HASRSEDyfFyXr5bkXrygPHamv4p9KTmk,1452
@@ -272,19 +273,20 @@ sourcecode/schemas/envelope-v1.schema.json,sha256=JJ4pAS8jZCYRp9uOoCbHkpUUpotVMI
 sourcecode/schemas/pr-impact-v1.schema.json,sha256=fC4DLqY--N5iJpm5wCxbUeILianYbhNDNYV3n4D5gFg,3756
 sourcecode/schemas/verify-edit-v1.schema.json,sha256=0jp-yoFIdmfq-4IrzrOPCAsEN7JcKg6cjq7-87_Ez0U,3537
 sourcecode/schemas/verify-v1.schema.json,sha256=rY1h_ub3hMAKCHO6WmnyKDtI4b37xLAEC6uuoEhKR64,3441
-sourcecode/telemetry/__init__.py,sha256=5jg6mIrhnt59FgxQsQcihxkHCWM07UFQFcuGwMPa9v8,3489
-sourcecode/telemetry/config.py,sha256=QPuTK-oc-Bg_EQftyFxLHPSnLRiZ5NegWYfX4BcD8iI,3842
+sourcecode/telemetry/__init__.py,sha256=9WpZjzY2HA3tasgsRep5v5dFzEWhZ8A8bYiY1P8GviI,4372
+sourcecode/telemetry/config.py,sha256=ZnF4FkluBAeTlSaivp-qsBoQe011HHsjH_DJw9CrqVI,5443
 sourcecode/telemetry/consent.py,sha256=-Wb8BFGXEexOs8M0Eja7F-T6ZtLNPeRoZnHcHvlP7-Q,2153
-sourcecode/telemetry/events.py,sha256=l3Z2SQUO4_C2D2ItXOOdVNimAmHedUHnUxqYFTxnsAE,2900
-sourcecode/telemetry/filters.py,sha256=-lqT2oorECuqEIdeHb--7AZ6BCaUx0bya720a-Z5x6w,7335
-sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
+sourcecode/telemetry/events.py,sha256=_ZBAo_U4UeW1GsnzHdPnVA8RDAz6U-pNPyQ3zfhaB3g,3089
+sourcecode/telemetry/filters.py,sha256=_3fid41dDWMdkM-2XzzzHVeUqD72nKPV9wQfjOUatEc,8378
+sourcecode/telemetry/lifecycle.py,sha256=QspRt5LfDLzAvgqmaxYAe04PZbBGIPsiPtsByKOlYuc,813
+sourcecode/telemetry/transport.py,sha256=BVjvRd1IrxQySl2XpT_T4abkodqOIjSULXcYLDMQriE,2551
 sourcecode/_docs/DEFECT-LEDGER.md,sha256=o2CY-nisHJOuYpn2qnUv2jVjEtSdnkiC-ilnu0kiFss,1233466
 sourcecode/_docs/LICENSE,sha256=23-fk61oSWGVmkWyka-FIM0rhAPM2hcYHnsaridL8Uo,1859
 sourcecode/_docs/NOTICE,sha256=Br-AA8Y3iJo1WXa5uP8QBpzqI5nDu3iGLbFyvDt3BOs,321
-sourcecode/_docs/USER_GUIDE.md,sha256=ta7lNm3q9ME6CyXZx4ttLh3sB2POEa2FeP5IE0GZoqY,108622
-sourcecode-5.9.31.dist-info/METADATA,sha256=TLlOxRRCLsXdoOy04SIYFjpNDl0I-xl_GimBpyKnk7A,67653
-sourcecode-5.9.31.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-5.9.31.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-5.9.31.dist-info/licenses/LICENSE,sha256=23-fk61oSWGVmkWyka-FIM0rhAPM2hcYHnsaridL8Uo,1859
-sourcecode-5.9.31.dist-info/licenses/NOTICE,sha256=Br-AA8Y3iJo1WXa5uP8QBpzqI5nDu3iGLbFyvDt3BOs,321
-sourcecode-5.9.31.dist-info/RECORD,,
+sourcecode/_docs/USER_GUIDE.md,sha256=fA3xYbXNM8_6be5c1Mi0qGw929TVvbbD9Hadl8dmUJ0,108622
+sourcecode-5.9.32.dist-info/METADATA,sha256=CTJuEtjpFyPm6AGLe4RS-V4zs5fn5DssD8sWPFlEcHU,67653
+sourcecode-5.9.32.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-5.9.32.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-5.9.32.dist-info/licenses/LICENSE,sha256=23-fk61oSWGVmkWyka-FIM0rhAPM2hcYHnsaridL8Uo,1859
+sourcecode-5.9.32.dist-info/licenses/NOTICE,sha256=Br-AA8Y3iJo1WXa5uP8QBpzqI5nDu3iGLbFyvDt3BOs,321
+sourcecode-5.9.32.dist-info/RECORD,,