sourcecode 5.9.30__tar.gz → 5.9.32__tar.gz

{sourcecode-5.9.30 → 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.30 → 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.30 → 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.30 → 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.30 → sourcecode-5.9.32}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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.*
+
+### Fixed
+
+- Successful Click exits no longer appear as failed `execution_completed` events.
+  Nonzero exits and unhandled exceptions retain `success=false` and emit only
+  the exception class as `error_kind`.
+- The telemetry schema now declares the MCP `tool` column used by the collector.
+
 ## [5.9.30] — 2026-09-02
 
 *A full pass over the open queue from the two 5.9.29 field audits. Nine rows

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.9.30
+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.30-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.30 — 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.30 → 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.30-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.30 — 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.30 → 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.30
+# ask 5.9.32
 ```
 
 Requires Python 3.9+.

sourcecode-5.9.32/docs/investigations/2026-09-11-ask-mcp-telemetry.md

@@ -0,0 +1,117 @@
+# Investigación: resultados ASK por MCP del 11 de septiembre de 2026
+
+Investigado el 12 de septiembre de 2026. Código histórico: release 5.8.20,
+commit `0370f9c`. Contraste: checkout 5.9.30. Datos del incidente: las ocho filas
+aportadas por el usuario; no se ha accedido al despliegue ni a la base de datos.
+
+## Conclusión
+
+**Los cuatro `execution_completed success=false` no demuestran cuatro fallos.**
+La instrumentación confunde la salida normal de Click con una excepción de error.
+El defecto existe tanto en 5.8.20 como en el checkout 5.9.30 anterior a esta corrección.
+
+La lectura más compatible con el código es actividad MCP con tres resultados de
+herramienta marcados como correctos y uno como error, junto con cuatro ejecuciones
+CLI internas cuya medición de éxito está dañada. La atribución de las filas
+`command_executed / mcp` a herramientas requiere confirmar qué colector estaba
+desplegado: el colector antiguo transforma exactamente así los eventos MCP.
+No es posible emparejar inequívocamente cada fila interna con una herramienta.
+
+El final de la tabla no prueba abandono, desinstalación ni un cierre del servidor.
+Una instalación anónima tampoco identifica por sí sola a una persona.
+
+## Evidencia confirmada
+
+1. En `src/sourcecode/cli.py`, `_get_command_with_preprocessing()._cmd_main()`
+   captura `BaseException`, pone `success=False` y vuelve a lanzar la excepción.
+   Click termina las invocaciones correctas en modo standalone con `SystemExit(0)`.
+   `CliRunner` recoge esa salida como código 0, pero el evento ya se emitió como fallo.
+   Esto también ocurre dentro de `src/sourcecode/mcp/runner.py`.
+2. `cmd=analyze` es una familia amplia. El wrapper también usa ese valor para
+   `prepare-context`, `version` y otros comandos. El campo `command` aporta la
+   distinción si el colector lo conserva; no estaba incluido en la tabla recibida.
+3. En 5.8.20, `get_delta` invoca `prepare-context delta … --since REF`, mientras que
+   `get_compact_context(git_context=True)` invoca `… --compact --git-context`.
+   Por tanto, los flags encajan con llamadas MCP documentadas, sin indicar por sí
+   solos que el agente inventase argumentos o usase mal la CLI.
+4. El hook de MCP emite `mcp_tool_invoked`, con `cmd=mcp` y el resultado de la
+   herramienta. El cliente 5.8.20 permite ese evento. El colector antiguo
+   (`41c3e1a`) no lo permite y aplica `event: pick(p.event, EVENTS, "command_executed")`.
+   Conserva `cmd` y `success`, pero pierde `tool` y `command`.
+   El colector del repositorio actualizado (`44834aa`) sí permite ese evento.
+   **Colector desplegado desactualizado: inferencia fuerte, no comprobación remota.**
+5. El wrapper CLI no enviaba `error_kind` ni el número de archivos.
+   Así se explican `error_kind=null` y `repo_size=unknown` incluso con un análisis
+   correcto; no son evidencias de que el repositorio no llegase a abrirse.
+6. Los eventos se envían en hilos independientes, con timeout y sin reintentos.
+   `received_at` es recepción, no inicio de ejecución. Puede haber pérdidas y
+   cambios de orden; no permite reconstruir con certeza la secuencia de llamadas.
+
+## Reproducción
+
+Sobre el código histórico, un repositorio temporal con dos commits y el recorrido
+real `FastMCP Tool.run → herramienta → CliRunner` reproduce:
+
+| Llamada | Resultado visible al agente | Evento CLI | Evento MCP |
+|---|---|---|---|
+| `get_delta(since="HEAD~1")` | Correcto, `success=true` | `success=false`, flags `--since` | `success=true` |
+| `get_compact_context(git_context=True)` | Correcto, `success=true` | `success=false`, flags `--compact --git-context` | `success=true` |
+| `get_delta(since="MISSING_REF")` | Error, `isError=true`, `EXECUTION_FAILED` | `success=false`, flags `--since` | `success=false` |
+
+La reproducción local usa macOS y Python 3.14; el incidente es Linux/Python 3.12.
+Confirma el defecto de instrumentación compartido, pero no reproduce el entorno,
+repositorio ni argumentos exactos de aquella instalación.
+
+## Qué pudo causar el fallo real
+
+Una referencia Git no disponible reproduce un error real con los mismos flags.
+También es relevante la selección automática de `get_delta`: prueba `origin/main`,
+después `origin/master`, y finalmente usa `HEAD~1`. Ese último ref no existe en un
+repositorio con un solo commit o un clon superficial sin padre disponible. Una
+ruta errónea, permisos o una excepción interna son otras posibilidades.
+
+No se conserva el valor de `--since`, el repositorio ni stderr por diseño. No hay
+base para elegir una de esas causas como explicación del caso concreto. Tampoco
+hay evidencia específica de incompatibilidad con Python 3.12 o Linux.
+
+## Correcciones locales y comprobación operativa pendiente
+
+- El wrapper distingue `SystemExit(0/None)` de salidas fallidas y conserva intacto
+  el comportamiento de Click. Para fallos emite solo la clase de excepción.
+  `SystemExit` no permite conocer por sí solo el motivo de un error CLI manejado.
+- Cinco pruebas de regresión cubren salida correcta, ayuda, opción inválida,
+  excepción sin datos privados y resultado correcto por el runner MCP. Las cinco
+  fallaban antes de la corrección.
+- El SQL declara y migra de forma idempotente `tool`: el colector ya intentaba
+  insertarlo, pero el esquema versionado no lo declaraba. Sin esa columna, desplegar
+  ese colector puede impedir inserciones. No se conoce el esquema remoto real.
+- Estos cambios son locales: no se ha publicado una versión ni desplegado SQL o
+  función. Las instalaciones 5.8.20 seguirán enviando el indicador defectuoso.
+
+Antes de usar métricas de éxito, comprobar la revisión de la función desplegada y
+las columnas existentes; migrar el esquema antes de desplegar el colector actualizado.
+No reinterpretar masivamente los falsos negativos históricos como éxitos: contienen
+tanto ejecuciones correctas como errores reales. No sumar eventos CLI y MCP como
+acciones independientes.
+
+Consulta de solo lectura para ampliar las filas sin exigir que las columnas
+`command` y `tool` ya existan:
+
+```sql
+select received_at, client_ts, event, cmd,
+       to_jsonb(t)->>'command' as command,
+       to_jsonb(t)->>'tool' as tool,
+       flags, success, error_kind, duration, v
+from public.telemetry_events as t
+where received_at >= timestamptz '2026-09-11 00:00:00+00'
+  and received_at <  timestamptz '2026-09-12 00:00:00+00'
+  and session = '03ff2232'
+  and install_id = '62d2d283-7369-476f-8828-3cd9f57169b3'
+order by received_at;
+```
+
+Para versiones publicadas con la corrección, contar éxito mediante
+`event='execution_completed' AND success IS TRUE` para invocaciones CLI, o
+`event='mcp_tool_invoked' AND success IS TRUE` para herramientas MCP, manteniendo
+separados ambos indicadores. Hasta confirmar la versión desplegada del colector,
+`command_executed / mcp` debe tratarse como señal heredada, no como arranques del servidor.

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.30 → sourcecode-5.9.32}/docs/privacy.md

@@ -63,7 +63,25 @@ 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
+
+`execution_completed` means the CLI invocation ended. It is not itself a success
+event. Successful process exits (`SystemExit(0)` or `SystemExit(None)`) must record
+`success=true`; nonzero exits and unhandled exceptions record `success=false` and
+only the exception class in `error_kind`, never its message.
+
+Historical warning: ASK 5.8.20, and the unpatched 5.9.30 source, recorded successful
+Click exits as failures. Those `execution_completed.success=false` rows cannot be
+used to calculate a failure rate or retrospectively relabelled as successes.
+MCP tool outcomes are a separate event stream; do not count both streams as
+independent user actions. See [the September 11 investigation](investigations/2026-09-11-ask-mcp-telemetry.md).
 
 ### MCP tool invocations
 
@@ -92,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)
@@ -180,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.30 → sourcecode-5.9.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "5.9.30"
+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.30 → 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.30"
+__version__ = "5.9.32"