feat: [AI-8448] count installs from the shell installers, not just npm (#1096)

Author: saravmajestic

docs/docs/reference/security-faq.md

@@ -145,10 +145,16 @@ A single `first_launch` event is sent containing only:
 
 - The installed version (e.g., "0.5.9")
 - Whether this is a fresh install or upgrade (boolean)
+- Which installer was used (`curl`, `powershell`, `npm`, `vscode-extension`, `local`, or `unknown` — what every upgrade from a version predating this field reports)
 - Your anonymous machine ID (random UUID)
 
 No code, queries, file paths, or personal information is included. This event helps us understand adoption and is fully opt-out-able.
 
+The install scripts (`altimate.sh/install`, `install.ps1`), the npm postinstall, and the VS Code extension's installer send nothing themselves and contact no telemetry endpoint. They only record the version and installer name to a local file that the CLI reads on its next run, so the opt-out above decides whether anything is ever transmitted.
+
+!!! warning "One caveat on the config-file opt-out"
+    The environment variables (`ALTIMATE_TELEMETRY_DISABLED`, `OPENCODE_DISABLE_TELEMETRY`) are always honoured. The `telemetry.disabled` **config key** is read during telemetry startup, which can run before the CLI's config is resolvable — and in that case startup currently proceeds with telemetry enabled. A user who has opted out via the config key alone may therefore still have this event transmitted. Use an environment variable if you need a guarantee.
+
 ## What happens when I authenticate via a well-known URL?
 
 When you run `altimate auth login <url>`, the CLI fetches `<url>/.well-known/altimate-code` to discover the server's auth command. Before executing anything:

docs/docs/reference/telemetry.md

@@ -42,7 +42,7 @@ We collect the following categories of events:
 | `feature_suggestion` | A post-connection feature suggestion is shown (suggestion_type, suggestions_shown, warehouse_type — no user input) |
 | `sql_execute_failure` | A SQL execution fails (warehouse type, query type, error message, PII-masked SQL — no raw values) |
 | `core_failure` | An internal tool error occurs (tool name, category, error class, truncated error message, PII-safe input signature, and optionally masked arguments — no raw values or credentials) |
-| `first_launch` | Fired once on first CLI run after installation. Contains version and is_upgrade flag. No PII. |
+| `first_launch` | Fired once on the first CLI run after an install or upgrade, triggered by a marker file the installer wrote — the installers themselves send nothing and contact no telemetry endpoint. Contains the installed version, `is_upgrade`, and `install_method` (`curl`, `powershell`, `npm`, `vscode-extension`, `local` for `install --binary`, or `unknown` for markers written before the field existed). `vscode-extension` starts appearing only once an extension build containing the marker write ships, so a zero share for it means the extension has not rolled out yet rather than no extension installs. No PII. **Reading `is_upgrade`:** it means "this machine had run altimate-code before", probed as whether `~/.altimate/machine-id` already existed — *not* "a binary was already present". A reinstall onto a machine that ever ran the CLI reports `is_upgrade: true`, and `altimate uninstall` leaves `machine-id` in place, so a metric excluding upgrades counts installs **per previously-unseen machine** and undercounts reinstalls onto known ones. (`is_upgrade` is a boolean in the event schema; it arrives in Application Insights `customDimensions` as a string, so KQL filters read `tostring(customDimensions.is_upgrade) != "true"`.) Delivery is at-most-once: the marker is deleted before the event flushes, so a process that dies first loses that install rather than re-firing it every launch. Local `--binary` installs report `version: "local"`. |
 | `task_outcome_signal` | Behavioral quality signal at session end — accepted, error, abandoned, or cancelled. Includes tool count, step count, duration, and last tool category. No user content. |
 | `task_classified` | Intent classification of the first user message using keyword matching — category (e.g. `debug_dbt`, `write_sql`, `optimize_query`), confidence score, and detected warehouse type. No user text is sent — only the classified category. |
 | `tool_chain_outcome` | Aggregated tool execution sequence at session end — ordered tool names (capped at 50), error count, recovery count, final outcome, duration, and cost. No tool arguments or outputs. |

install

@@ -487,11 +487,55 @@ install_from_binary() {
     chmod 755 "$dest_path"
 }
 
+# Write the same post-install marker that npm's postinstall.mjs writes, so the
+# CLI emits its `first_launch` telemetry event on the next run. Without this the
+# curl install path — the one advertised at altimate.sh/install — produces no
+# install event at all, and every curl user is invisible in install metrics.
+#
+# The path MUST match welcome.ts's data-dir resolution ($XDG_DATA_HOME, falling
+# back to ~/.local/share) on every platform, including Windows: the CLI reads it
+# via Node's os.homedir() and never consults %LOCALAPPDATA%.
+#
+# No network call and no identifier is written here — this only hands the CLI the
+# version it was installed at. Whether anything is ever sent remains entirely up
+# to the CLI's existing telemetry opt-out gates.
+# $1 — install_method to record. Must be a value in the CLI's allowlist
+# (packages/opencode/src/cli/welcome.ts); anything else reports as "unknown".
+write_install_marker() {
+    local marker_source="$1"
+    local data_dir="${XDG_DATA_HOME:-$HOME/.local/share}/altimate-code"
+    # An empty marker is deleted unread by the CLI, so fall back to "unknown"
+    # rather than losing the install: $specific_version is empty whenever the
+    # GitHub API could not be reached (see check_version).
+    local marker_version="${specific_version:-unknown}"
+    mkdir -p "$data_dir" 2>/dev/null || return 0
+    # Companion first, trigger last: the CLI returns early unless .installed-version
+    # exists, then consumes .install-source. Trigger-first would let a CLI starting in
+    # between report install_method "unknown", and a truncated .installed-version is
+    # deleted unread — losing the install rather than just its attribution.
+    printf '%s' "$marker_source" > "$data_dir/.install-source" 2>/dev/null || return 0
+    # The trigger is published atomically. Companion-first alone only closes the
+    # "attribution lost" window; a plain redirect truncates before filling, so a CLI
+    # starting mid-write can still observe an EMPTY .installed-version, which it
+    # deletes unread — losing the install itself. mv within one directory is atomic.
+    local tmp="$data_dir/.installed-version.$$"
+    printf '%s' "${marker_version#v}" > "$tmp" 2>/dev/null || return 0
+    mv -f "$tmp" "$data_dir/.installed-version" 2>/dev/null || { rm -f "$tmp" 2>/dev/null; return 0; }
+}
+
 if [ -n "$binary_path" ]; then
     install_from_binary
+    # Attributed as "local", not "curl": --binary installs a file the caller already
+    # had (dev build, air-gapped artifact) and sets specific_version="local", so
+    # folding it into the curl metric would misreport both source and version.
+    # Still recorded — it is a real install — just not a curl one.
+    write_install_marker "local"
 else
     check_version
     download_and_install
+    # Only reached when an install actually happened: check_version exits 0 early
+    # when the requested version is already present.
+    write_install_marker "curl"
 fi
 
 

install.ps1

@@ -304,6 +304,71 @@ if (-not $needsBaseline) {
   }
 }
 
+# ---------------------------------------------------------------------------
+# Post-install marker (install telemetry)
+# ---------------------------------------------------------------------------
+# Mirrors npm's postinstall.mjs (and ./install's write_install_marker) so the CLI
+# emits its `first_launch` event on the next run; without it this install path is
+# invisible in install metrics.
+#
+# A function, not inline code, so the Pester suite can AST-extract and execute it
+# against a temp profile the same way it does Test-Checksum. The subprocess tests
+# deliberately stop the installer before this point, so inline code here would have
+# no runtime coverage on the riskiest of the writers.
+function Write-InstallMarker {
+  param([string]$Version)
+
+  # The directory MUST match welcome.ts's resolution - $XDG_DATA_HOME, else
+  # <home>\.local\share - because the CLI reads it through Node's os.homedir() and
+  # never looks at %LOCALAPPDATA%. Writing to LOCALAPPDATA here would be silently
+  # ignored at read time.
+  #
+  # No network call and no identifier is written; only the installed version is
+  # recorded. The CLI's existing telemetry opt-out gates still decide whether
+  # anything is ever sent.
+  #
+  # EVERYTHING is inside the try, path computation included. $ErrorActionPreference is
+  # "Stop", and Join-Path resolves provider-qualified paths - so a null or empty
+  # $env:USERPROFILE (pwsh on non-Windows, a stripped service profile) or an
+  # XDG_DATA_HOME naming a non-existent PSDrive raises a TERMINATING error. Computed
+  # outside the try, that error would abort the installer after the binary is placed
+  # but before the PATH registry write and the "Get started" output, leaving the user
+  # with an installed binary that is not on PATH. [IO.Path]::Combine also keeps
+  # PSDrive resolution out of it entirely.
+  try {
+    $dataRoot = if ($env:XDG_DATA_HOME) { $env:XDG_DATA_HOME } else { [IO.Path]::Combine($env:USERPROFILE, ".local", "share") }
+    $dataDir = [IO.Path]::Combine($dataRoot, "altimate-code")
+    New-Item -ItemType Directory -Force -Path $dataDir | Out-Null
+    # The CLI deletes an empty marker without reporting, so fall back to "unknown"
+    # when the version could not be resolved (GitHub API unreachable).
+    $markerVersion = if ($Version) { $Version -replace '^v', '' } else { "unknown" }
+    # -NoNewline: the CLI trims, but keep the file byte-identical to the npm path.
+    #
+    # -Encoding ascii, not utf8: the documented entrypoint is `powershell -c "irm ... | iex"`,
+    # i.e. Windows PowerShell 5.1, where `-Encoding utf8` prepends a UTF-8 BOM. Both values are
+    # ASCII by construction, so ascii is lossless here and cannot emit one. The CLI's .trim()
+    # happens to strip a leading BOM (U+FEFF is JS whitespace), but the install-source value is
+    # matched against a fixed allowlist and must not depend on that.
+    #
+    # Companion first, trigger last. The CLI returns early unless .installed-version
+    # exists, then consumes .install-source - so writing the trigger first would let a
+    # CLI starting in between report install_method "unknown". Set-Content also
+    # truncates before writing, and an empty .installed-version is deleted unread,
+    # which would lose the install outright.
+    Set-Content -Path ([IO.Path]::Combine($dataDir, ".install-source")) -Value "powershell" -NoNewline -Encoding ascii
+    # Trigger published atomically: Set-Content truncates before writing, so a CLI
+    # starting mid-write could observe an EMPTY .installed-version and delete it
+    # unread, losing the install. Move-Item within one directory is atomic.
+    $tmpMarker = [IO.Path]::Combine($dataDir, ".installed-version.tmp")
+    Set-Content -Path $tmpMarker -Value $markerVersion -NoNewline -Encoding ascii
+    Move-Item -Force -Path $tmpMarker -Destination ([IO.Path]::Combine($dataDir, ".installed-version"))
+  } catch {
+    # Non-fatal - a missing marker only costs us the install event, never the install.
+  }
+}
+
+Write-InstallMarker -Version $specificVersion
+
 # ---------------------------------------------------------------------------
 # PATH (user scope, via registry + broadcast)
 # ---------------------------------------------------------------------------

packages/opencode/script/postinstall.mjs

@@ -238,7 +238,20 @@ function writeUpgradeMarker(version) {
     const xdgData = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share")
     const dataDir = path.join(xdgData, "altimate-code")
     fs.mkdirSync(dataDir, { recursive: true })
-    fs.writeFileSync(path.join(dataDir, ".installed-version"), version.replace(/^v/, ""))
+    // Companion first, trigger last. `.installed-version` is what the CLI keys on:
+    // it returns early unless that file exists, then consumes `.install-source`.
+    // Trigger-first left two windows — a CLI starting in between reports
+    // install_method "unknown", and writeFileSync truncates before writing, so a
+    // reader could observe an EMPTY `.installed-version` and delete it unread,
+    // losing the install outright. Matches `install` and `install.ps1`.
+    fs.writeFileSync(path.join(dataDir, ".install-source"), "npm")
+    // Trigger published atomically: writeFileSync truncates before filling, so a CLI
+    // starting mid-write could observe an EMPTY `.installed-version` and delete it
+    // unread, losing the install. renameSync within one directory is atomic.
+    const versionPath = path.join(dataDir, ".installed-version")
+    const tmpPath = `${versionPath}.${process.pid}.tmp`
+    fs.writeFileSync(tmpPath, version.replace(/^v/, ""))
+    fs.renameSync(tmpPath, versionPath)
   } catch {
     // Non-fatal — the CLI just won't show a welcome banner
   }

packages/opencode/src/altimate/telemetry/index.ts

@@ -474,6 +474,11 @@ export namespace Telemetry {
         session_id: string
         version: string
         is_upgrade: boolean
+        // altimate_change — which installer wrote the marker. Recorded by the
+        // installer itself; "unknown" when the marker predates this field or the
+        // source file was unreadable. Without it, curl and npm installs are
+        // indistinguishable in the same metric.
+        install_method: "curl" | "powershell" | "npm" | "vscode-extension" | "local" | "unknown"
       }
     // altimate_change end
     // altimate_change start — telemetry for skill management operations