sourcecode 5.9.31__tar.gz → 5.9.32__tar.gz

{sourcecode-5.9.31 → sourcecode-5.9.32}/.github/workflows/build-windows.yml

@@ -3,6 +3,10 @@ name: Build Windows EXE
 on:
   workflow_dispatch:
 
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   build-windows:
     runs-on: windows-latest

{sourcecode-5.9.31 → sourcecode-5.9.32}/.github/workflows/perf-gate.yml

@@ -29,6 +29,10 @@ concurrency:
   group: perf-gate
   cancel-in-progress: false
 
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   gate:
     runs-on: ubuntu-latest

{sourcecode-5.9.31 → sourcecode-5.9.32}/.github/workflows/windows-battery.yml

@@ -12,6 +12,10 @@ concurrency:
   group: windows-battery-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   battery:
     runs-on: windows-latest

{sourcecode-5.9.31 → sourcecode-5.9.32}/.github/workflows/windows-regression.yml

@@ -10,6 +10,10 @@ on:
 # observe Git Bash rewriting a route argument such as `/owners` to an absolute
 # Windows path.  Keep both the normal Python regression suite and the actual
 # Git Bash invocation on a Windows runner.
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   windows-cli:
     runs-on: windows-latest

{sourcecode-5.9.31 → sourcecode-5.9.32}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [5.9.32] — 2026-09-15
+
+*Patch release adding safe, explicit PyPI update notifications and installation.*
+
+### Added
+
+- `ask version` and `ask update --check` report when a newer ASK release exists.
+- `ask update` asks for confirmation; `ask update --yes` is the explicit
+  non-interactive form.
+- MCP agents can use `check_for_updates()` and `update_ask(confirm=true)`.
+- Updates use the active Python interpreter, serialize concurrent installs,
+  verify the installed distribution, and attempt rollback after a failed pip run.
+- Update checks are cached for 24 hours and can be disabled with
+  `SOURCECODE_UPDATE_DISABLED=1`.
+
 ## [5.9.31] — 2026-09-12
 
 *Patch release correcting MCP/CLI telemetry outcomes and the telemetry schema.*

{sourcecode-5.9.31 → sourcecode-5.9.32}/PKG-INFO

@@ -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 → sourcecode-5.9.32}/README.md

@@ -10,7 +10,7 @@
 > 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
@@ -241,7 +241,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.32/SPEC-update-notifications.md

@@ -0,0 +1,85 @@
+# Spec: ASK update notifications and opt-in self-update
+
+## Objective
+
+Informar de forma no intrusiva cuando existe una versión más reciente de ASK y
+permitir actualizarla únicamente tras una confirmación explícita. El mismo estado
+debe estar disponible para un agente MCP sin identificar al usuario ni bloquear un
+análisis normal.
+
+## Commands and interfaces
+
+```text
+ask update --check       # consulta y muestra la versión disponible; no instala
+ask update               # consulta; pide confirmación en TTY; instala solo con sí
+ask update --yes         # instala tras la intención explícita del operador
+MCP check_for_updates()  # respuesta estructurada, sin instalar
+MCP update_ask(confirm)  # confirm=false informa; confirm=true instala
+```
+
+La comprobación automática, si se habilita más adelante, tendrá como máximo una
+consulta cacheada al día y nunca se ejecutará durante un comando de análisis.
+
+## Project structure
+
+- `src/sourcecode/update.py` — consulta, comparación, caché y actualización.
+- `src/sourcecode/cli.py` — comandos y confirmación TTY.
+- `src/sourcecode/mcp/server.py` — herramientas MCP estructuradas.
+- `tests/test_update.py` — red, caché, comparación, confirmación e instalación.
+- `docs/update.md` — comportamiento, permisos y recuperación.
+
+## Safety and behavior
+
+- Consultar únicamente el endpoint oficial HTTPS de PyPI:
+  `https://pypi.org/pypi/sourcecode/json`, y aceptar respuestas JSON con versión
+  semántica válida.
+- No ejecutar código descargado directamente: delegar en
+  `sys.executable -m pip install --upgrade sourcecode`.
+- Mostrar versión actual, versión objetivo, intérprete y comando antes de instalar.
+- No actualizar si el entorno es CI, pytest, desarrollo editable o si
+  `SOURCECODE_TELEMETRY_CONTEXT` no es `production`.
+- No usar `sudo`, no modificar archivos del proyecto y no enviar credenciales.
+- Timeout corto, errores silenciosos en la comprobación y errores explícitos en una
+  actualización solicitada.
+- Una sola actualización por entorno a la vez, validación de la distribución
+  instalada y recuperación al intentar restaurar la versión anterior si pip falla.
+- `--yes` solo evita la pregunta; no convierte una comprobación en actualización.
+- Tras instalar, verificar que la versión cargada coincide con la objetivo y sugerir
+  reiniciar procesos MCP persistentes.
+
+## Testing strategy
+
+- Respuestas inválidas, timeout y versiones iguales/no válidas.
+- Caché diaria y ausencia de red en CI/tests.
+- Confirmación no interactiva sin `--yes` no instala.
+- `--yes` ejecuta exactamente el intérprete actual y el paquete `sourcecode`.
+- MCP nunca instala con `confirm=false` y devuelve resultado estructurado.
+- Nunca se muestran ni transmiten rutas, tokens o datos del usuario.
+
+## Boundaries
+
+- Always: pedir consentimiento antes de instalar, usar el intérprete actual y
+  verificar el resultado.
+- Ask first: activar comprobación automática al inicio de comandos de análisis;
+  cambiar el paquete o índice consultado.
+- Never: autoactualizar sin consentimiento, usar `sudo`, ejecutar scripts remotos o
+  actualizar un proceso MCP en caliente.
+- `SOURCECODE_UPDATE_DISABLED=1` desactiva tanto las comprobaciones como las
+  instalaciones solicitadas (útil para políticas corporativas).
+
+## Success criteria
+
+1. Un usuario puede conocer la última versión con `ask update --check`.
+2. `ask update` ofrece actualizar y solo instala tras “sí”.
+3. Un agente puede consultar el estado mediante MCP y solicitar la actualización
+   con `confirm=true`.
+4. CI/tests/desarrollo no generan consultas ni instalaciones.
+5. Los tests cubren todos los casos de seguridad anteriores.
+
+## Open questions
+
+- ¿Debe la notificación automática aparecer al inicio de todos los comandos o solo
+  en `ask version`/`ask update`? Esta especificación propone no interrumpir análisis
+  hasta obtener una decisión explícita.
+- PyPI oficial es el único índice soportado inicialmente. Un índice alternativo
+  requerirá una especificación y decisión separadas.

{sourcecode-5.9.31 → sourcecode-5.9.32}/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-5.9.32/docs/investigations/2026-09-15-telemetry-audit.md

@@ -0,0 +1,50 @@
+# Auditoría de telemetría ASK — diagnóstico previo (2026-09-15)
+
+Diagnóstico escrito antes de modificar productores, receptor o tests. Revisión local;
+no se ha accedido a la base de producción ni a los logs de Actions. Los números
+históricos son evidencia aportada por el solicitante, no mediciones verificadas aquí.
+
+## Mapa
+
+CLI `cli.py:_get_command_with_preprocessing/_cmd_main` → `telemetry.record`
+→ `TelemetryEvent` → `filters.sanitize` → `transport.send` (hilo daemon por evento,
+sin cola persistente/reintentos) → HTTPS Supabase `functions/telemetry/index.ts`
+→ INSERT `public.telemetry_events` → `sql/telemetry_events.sql` (retención 90 días).
+
+MCP `server.py:FastMCP.Tool.run` → herramienta → `runner.run_command/CliRunner`
+→ wrapper CLI anterior; además `_record_tool_invocation` emite `mcp_tool_invoked`.
+Licensing `license.py:_emit_telemetry` → activation / gate_blocked → mismo recorder.
+`cli.py:telemetry_enable` emite telemetry_enabled. No productor actual de
+command_executed, execution_failed ni telemetry_disabled. El receptor convierte
+nombres desconocidos a command_executed.
+
+## Hallazgos
+
+| Finding / estado | Evidence | Root cause | Impact on analytics | Severity | Proposed fix |
+|---|---|---|---|---|---|
+| CONFIRMED: tests/CI pueden enviar a producción | config.is_enabled devuelve True en CI; test_telemetry_on_by_default_in_ci lo exige; conftest no aísla red; workflows Windows ejecutan pytest/CLI sin exclusión | default-on sin detección ni defensa en transporte | tests cuentan como instalaciones/ejecuciones | P0 | contexto runtime, bloqueo de red sintética, env global suite/workflows |
+| HIGH-CONFIDENCE: ráfagas Windows compatibles con batería | windows-battery ejecuta pytest en runner efímero, varios procesos xdist; endpoint por defecto real | HOME del runner nuevo + UUID por configuración | adquisición inflada | P0 | excluir CI antes de crear ID; no atribuir filas concretas sin logs |
+| CONFIRMED: carrera creando ID | config.get_install_id lee JSON, escribe sin lock, devuelve UUID propio aunque otro proceso haya sobrescrito | read-modify-write no atómico; _save trunca config | múltiples IDs / corrupción | P0 | identidad independiente publicada atómicamente; migrar UUID legado |
+| CONFIRMED: NULL intencional por fallo de persistencia | get_install_id devuelve cadena vacía; sanitize omite install; receptor uuid devuelve null | degradación deliberada a evento sin identidad | días con eventos y cero instalaciones | P0 | no enviar si identidad estable no disponible; validar v2 en receptor |
+| NOT-REPRODUCED: actualizar versión regenera ID | ruta fija ~/.config/sourcecode/config.json, no usa versión/venv | no hay ruta de actualización que regenere | no atribuir rotación a pip sin pruebas | P0 | test de actualización; documentar HOME/volúmenes/config compartidos |
+| CONFIRMED histórico: éxito marcado false | git show 129fd04^:cli.py captura BaseException incluyendo SystemExit(0); investigación 2026-09-11 reproduce MCP | Click termina con SystemExit incluso con éxito | tasa de éxito histórica inválida | P0 | conservar fix 129fd04; versionar contrato; no reparar filas por suposición |
+| CONFIRMED: failed=0 pese a errores | _cmd_main siempre emite execution_completed; ningún productor execution_failed | evento terminal único sin resultado tipado | errores/negativos/excepciones mezclados | P0 | outcome explícito, inicio correlacionado, failed para error real detectado |
+| CONFIRMED: MCP doble dimensión sin correlación | Tool.run emite y CliRunner emite; session global de 8 hex por proceso | sumar eventos duplica acciones; sesión no es llamada ni usuario | engagement inflado | P1 | UUID ejecución, parent, interface mcp; separar herramientas y comandos |
+| CONFIRMED: sesión por proceso importado | telemetry._SESSION inicializado al importar | 32 bits y herencia por fork | colisiones y sesiones indistinguibles | P1 | 128 bits, renovar por PID; documentar proceso MCP persistente |
+| CONFIRMED: licensing ya separado por evento | activate_license emite activation InvalidLicense; gates emiten gate_blocked | agregación success/error_kind sin event mezcla dominios | atribuir incapacidad/churn sin evidencia | P1 | outcome de dominio y excluir licensing de errores de ejecución |
+| CONFIRMED: flags usa allowlist | filters._SAFE_FLAGS y receptor FLAGS descartan valores | protección existente adecuada; comando buscado entre todos los tokens puede tomar un valor como comando | privacidad preservada para flags, dimensión comando incorrecta | P1 | mantener allowlist, usar contexto Click para comando; capacidades semánticas |
+| CONFIRMED: falta versión de schema | v es versión producto; schema sin campo de contrato | cambios de significado no distinguibles | mezcla de generaciones | P1 | schema_version 2, filas anteriores legacy/unknown |
+| CONFIRMED: pérdidas no medibles | transporte daemon sin flush/retry; rate limit 120/min por IP | salida rápida, red, NAT y límites descartan eventos | conteos observados son incompletos | P1 | flush acotado, documentar límite y no inferir crash de inicio huérfano |
+| SUSPECTED: receptor remoto antiguo | investigación previa documenta coerción de mcp_tool_invoked y falta de tool en esquema antiguo | despliegue posiblemente desincronizado | MCP perdido o inserts fallidos | P1 | migración antes de receptor, no afirmar estado remoto |
+
+## Identidad y límites de atribución
+
+La identidad actual pertenece a la configuración del HOME, no al paquete instalado.
+CLI y MCP usan el mismo módulo en el mismo proceso/HOME. pip/pipx/venv no intervienen;
+HOME temporal, borrado de configuración o contenedor sin volumen sí cambian identidad.
+Copiar un HOME/imagen con ID fusiona instalaciones. No hay prueba de qué UUID histórico
+creó qué job. Tests que parchean _CONFIG_FILE generan UUID en tmp_path; otros CLI tests
+usan directamente el HOME del runner. No se han visto fixtures que envíen UUID fijados.
+
+No deducir humano/bot del uso MCP ni del volumen. Contexto production significa
+«sin señales sintéticas detectadas», nunca prueba de persona externa.

{sourcecode-5.9.31 → sourcecode-5.9.32}/docs/privacy.md

@@ -63,7 +63,12 @@ When telemetry is enabled, these fields are sent per command invocation:
 | `success` | `true` | Whether the command succeeded |
 | `error_kind` | `FileNotFoundError` | Exception class name only, no message |
 | `tool` | `get_compact_context` | MCP tool name only, on `mcp_tool_invoked` events (see below) |
-| `session` | `a3f2c1b0` | 8-char random hex, ephemeral, never persisted |
+| `session` | `7f…` | 32-char random hex, process-scoped and never persisted |
+| `schema_version` | `2` | Telemetry contract version, distinct from ASK `v` |
+| `telemetry_context` | `production` | Runtime origin; `test`, `ci`, and `development` are suppressed |
+| `interface` | `cli` / `mcp` | Invocation surface, never a person identifier |
+| `outcome` | `succeeded` | `started`, `succeeded`, `negative`, `expected_error`, `internal_error`, or `cancelled` |
+| `execution_id` | UUID | Per invocation correlation token; `parent_execution_id` links nested MCP CLI calls |
 
 ### Interpreting execution outcomes
 
@@ -105,7 +110,7 @@ File counts are converted to anonymous ranges before sending:
 
 ### Session identifier
 
-The `session` field is an 8-character random hex string generated fresh each time `sourcecode` runs. It is:
+The `session` field is a 32-character random hex string generated fresh for each process (and refreshed after a fork). It is:
 - **Never persisted** to disk
 - **Never reused** across invocations
 - Only useful for correlating multiple events within a single run (e.g., start + completion)
@@ -193,12 +198,22 @@ The first time you run `ask` interactively (not in CI, not piped), you are shown
 
 ---
 
-## CI environments
+## CI, tests, and development environments
 
-Telemetry remains on in CI unless `SOURCECODE_TELEMETRY=0` or `DO_NOT_TRACK=1` is set. CI is detected only to skip the first-run notice, which has no terminal to appear on:
+Production telemetry is suppressed whenever a standard CI marker (`CI`, `GITHUB_ACTIONS`, and similar), pytest, or an explicit `SOURCECODE_TELEMETRY_CONTEXT` of `test`, `ci`, or `development` is present. This happens before an install ID is created and before the transport opens a connection. A deliberate production deployment must run outside these markers; `SOURCECODE_TELEMETRY=1` cannot override the origin guard. The first-run notice is also skipped:
 
 `CI`, `CONTINUOUS_INTEGRATION`, `GITHUB_ACTIONS`, `CIRCLECI`, `TRAVIS`, `JENKINS_URL`, `BUILDKITE`, `GITLAB_CI`, `TF_BUILD`, `TEAMCITY_VERSION`, `DRONE`, `SEMAPHORE`
 
+## Contract and analytics limits
+
+Schema 2 is the population used by the product queries. Legacy rows remain
+queryable with unknown origin/outcome and are never retroactively relabelled.
+`install_id` identifies a persisted ASK configuration, not a person: cloned homes
+merge installations and deleted or ephemeral homes create new ones. Counts are
+observed installations and lower bounds on activity, not a count of real users.
+MCP intensity is agentic usage evidence, never evidence that a human or bot initiated
+it. See [telemetry_product_metrics.sql](../supabase/sql/telemetry_product_metrics.sql).
+
 ---
 
 ## Open source auditability

sourcecode-5.9.32/docs/update.md

@@ -0,0 +1,22 @@
+# ASK updates
+
+`ask update --check` consults the official PyPI JSON endpoint and reports the
+installed and latest versions. Results are cached for 24 hours. A normal
+`ask update` asks for confirmation in an interactive terminal; `ask update --yes`
+is the explicit non-interactive form.
+
+The installer runs `sys.executable -m pip install --upgrade sourcecode`, so the
+same Python environment that launched ASK is updated. It never uses `sudo`, runs
+remote scripts, or changes the repository. Persistent MCP servers must be
+restarted after an update.
+
+Checks and installations are suppressed in CI, pytest, editable development
+checkouts, and other non-production telemetry contexts. Network failures leave
+ASK unchanged. The MCP equivalents are `check_for_updates()` and
+`update_ask(confirm=true)`; `confirm=false` only checks status.
+
+Only one update may run for an environment at a time. After pip returns, ASK
+verifies the installed distribution metadata. If installation fails, it attempts
+to restore the previously installed version and reports whether restoration
+succeeded. Set `SOURCECODE_UPDATE_DISABLED=1` to disable update checks and
+installation for managed environments.

{sourcecode-5.9.31 → sourcecode-5.9.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "5.9.31"
+version = "5.9.32"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-5.9.31 → sourcecode-5.9.32}/src/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-5.9.31 → sourcecode-5.9.32}/src/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")