@openagentsinc/pylon 0.1.3 → 0.1.5

package/src/index.js

@@ -5,6 +5,12 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
+import {
+  installSourceForTelemetry,
+  telemetryFailureContext,
+} from "./telemetry.js";
+
+export { createTelemetryClient } from "./telemetry.js";
 
 export const DEFAULT_RELEASE_REPO = "OpenAgentsInc/openagents";
 export const DEFAULT_RELEASE_API_BASE = "https://api.github.com";
@@ -18,6 +24,9 @@ const PYLON_RELEASE_TAG_PREFIX = "pylon-v";
 const RELEASE_ASSET_INSTALL_METHOD = "release_asset";
 const SOURCE_BUILD_INSTALL_METHOD = "source_build";
 const PREFERRED_RUNTIME_MODEL_NAME = "gemma4:e4b";
+const LEGACY_SOURCE_BUILD_SIBLING_REPOSITORIES = {
+  "spark-sdk": "https://github.com/AtlantisPleb/spark-sdk.git",
+};
 
 function emitStatus(onStatus, message, detail = null) {
   if (typeof onStatus === "function") {
@@ -31,10 +40,82 @@ function emitVerboseStatus(onStatus, verbose, message, detail = null) {
   }
 }
 
+function emitTelemetry(telemetryClient, eventName, properties = {}) {
+  if (typeof telemetryClient?.emit === "function") {
+    void telemetryClient.emit(eventName, properties);
+  }
+}
+
 function normalizeVersion(value) {
   return value.replace(/^pylon-v/, "").replace(/^v/, "");
 }
 
+function parseComparableVersion(value) {
+  const normalized = normalizeVersion(value).trim();
+  const match = normalized.match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+?)(\d+)?)?$/,
+  );
+  if (!match) {
+    return null;
+  }
+
+  return {
+    normalized,
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2], 10),
+    patch: Number.parseInt(match[3], 10),
+    prereleaseLabel: match[4] ?? null,
+    prereleaseNumber:
+      match[5] != null ? Number.parseInt(match[5], 10) : null,
+  };
+}
+
+function comparePylonReleaseTags(leftTagName, rightTagName) {
+  const left = parseComparableVersion(leftTagName);
+  const right = parseComparableVersion(rightTagName);
+
+  if (!left && !right) {
+    return String(leftTagName).localeCompare(String(rightTagName));
+  }
+  if (!left) {
+    return -1;
+  }
+  if (!right) {
+    return 1;
+  }
+
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) {
+      return left[key] > right[key] ? 1 : -1;
+    }
+  }
+
+  if (left.prereleaseLabel == null && right.prereleaseLabel == null) {
+    return 0;
+  }
+  if (left.prereleaseLabel == null) {
+    return 1;
+  }
+  if (right.prereleaseLabel == null) {
+    return -1;
+  }
+
+  const labelComparison = left.prereleaseLabel.localeCompare(
+    right.prereleaseLabel,
+  );
+  if (labelComparison !== 0) {
+    return labelComparison;
+  }
+
+  const leftNumber = left.prereleaseNumber ?? 0;
+  const rightNumber = right.prereleaseNumber ?? 0;
+  if (leftNumber !== rightNumber) {
+    return leftNumber > rightNumber ? 1 : -1;
+  }
+
+  return left.normalized.localeCompare(right.normalized);
+}
+
 function createBootstrapError(message, context = {}) {
   const error = new Error(message);
   Object.assign(error, context);
@@ -50,6 +131,27 @@ async function pathExists(value) {
   }
 }
 
+async function findFilesNamed(rootDir, targetName, results = []) {
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "target") {
+      continue;
+    }
+
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      await findFilesNamed(fullPath, targetName, results);
+      continue;
+    }
+
+    if (entry.isFile() && entry.name === targetName) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
 function defaultInstallRoot() {
   return path.join(os.homedir(), ".openagents", "pylon", "bootstrap");
 }
@@ -497,14 +599,31 @@ export function isPylonReleaseTag(tagName) {
   );
 }
 
-export function selectLatestPylonRelease(releases) {
+function releaseHasTargetAssets(release, target) {
+  if (!target || !release?.tag_name) {
+    return false;
+  }
+
+  const { archiveName, checksumName } = buildAssetNames(release.tag_name, target);
+  const assetNames = new Set(
+    (Array.isArray(release.assets) ? release.assets : [])
+      .map((asset) => asset?.name)
+      .filter(Boolean),
+  );
+  return assetNames.has(archiveName) && assetNames.has(checksumName);
+}
+
+export function selectLatestPylonRelease(releases, target = null) {
   if (!Array.isArray(releases)) {
     throw new Error("GitHub release lookup did not return a release list.");
   }
 
-  const release = releases.find(
-    (candidate) => !candidate?.draft && isPylonReleaseTag(candidate?.tag_name),
-  );
+  const candidates = releases
+    .filter((candidate) => !candidate?.draft && isPylonReleaseTag(candidate?.tag_name))
+    .sort((left, right) => comparePylonReleaseTags(right.tag_name, left.tag_name));
+  const release =
+    candidates.find((candidate) => releaseHasTargetAssets(candidate, target)) ??
+    candidates[0];
   if (!release) {
     throw new Error(
       `GitHub release lookup did not find any published ${PYLON_RELEASE_TAG_PREFIX} releases.`,
@@ -522,6 +641,7 @@ export async function fetchReleaseMetadata({
   apiBase = DEFAULT_RELEASE_API_BASE,
   repo = DEFAULT_RELEASE_REPO,
   version = null,
+  target = null,
 } = {}) {
   const normalizedVersion = normalizeRequestedVersion(version);
   const endpoint = normalizedVersion
@@ -538,7 +658,7 @@ export async function fetchReleaseMetadata({
       ? "GitHub tagged release lookup"
       : "GitHub release list lookup",
   });
-  return normalizedVersion ? payload : selectLatestPylonRelease(payload);
+  return normalizedVersion ? payload : selectLatestPylonRelease(payload, target);
 }
 
 export function selectReleaseAssets(release, target) {
@@ -704,6 +824,105 @@ function manualSourceBuildCommands(tagName, cloneUrl) {
   ].join("\n");
 }
 
+function inferLegacySiblingRepositoryName(relativeDependencyPath) {
+  if (typeof relativeDependencyPath !== "string" || !relativeDependencyPath.startsWith("..")) {
+    return null;
+  }
+
+  const segments = relativeDependencyPath
+    .split(/[\\/]+/)
+    .filter(Boolean);
+  const firstRepoSegment = segments.find((segment) => segment !== "..");
+  if (!firstRepoSegment) {
+    return null;
+  }
+
+  return Object.hasOwn(LEGACY_SOURCE_BUILD_SIBLING_REPOSITORIES, firstRepoSegment)
+    ? firstRepoSegment
+    : null;
+}
+
+async function discoverLegacySiblingRepositories(repoDir) {
+  const cargoTomlFiles = await findFilesNamed(repoDir, "Cargo.toml");
+  const discovered = new Set();
+
+  for (const cargoTomlPath of cargoTomlFiles) {
+    const payload = await fs.readFile(cargoTomlPath, "utf8");
+    const matches = payload.matchAll(/path\s*=\s*"([^"]+)"/g);
+    for (const match of matches) {
+      const dependencyPath = match[1]?.trim();
+      const repoName = inferLegacySiblingRepositoryName(dependencyPath);
+      if (!repoName) {
+        continue;
+      }
+
+      const resolvedPath = path.resolve(path.dirname(cargoTomlPath), dependencyPath);
+      if (resolvedPath.startsWith(`${repoDir}${path.sep}`) || resolvedPath === repoDir) {
+        continue;
+      }
+
+      discovered.add(repoName);
+    }
+  }
+
+  return [...discovered];
+}
+
+async function hydrateLegacySiblingRepositories({
+  repoDir,
+  buildEnv,
+  runProcessImpl,
+  onStatus,
+  telemetryClient,
+  releaseTag,
+  target,
+}) {
+  const repoNames = await discoverLegacySiblingRepositories(repoDir);
+  const workspaceRoot = path.dirname(repoDir);
+
+  for (const repoName of repoNames) {
+    const cloneUrl = LEGACY_SOURCE_BUILD_SIBLING_REPOSITORIES[repoName];
+    const checkoutDir = path.join(workspaceRoot, repoName);
+    if (!cloneUrl || (await pathExists(checkoutDir))) {
+      continue;
+    }
+
+    emitStatus(onStatus, "Hydrating legacy sibling checkout", repoName);
+    emitTelemetry(telemetryClient, "installer_legacy_sibling_checkout_started", {
+      release_tag: releaseTag,
+      os: target.os,
+      arch: target.arch,
+      repository: repoName,
+    });
+
+    try {
+      await runProcessImpl(
+        "git",
+        ["clone", "--depth", "1", cloneUrl, checkoutDir],
+        {
+          cwd: workspaceRoot,
+          env: buildEnv,
+        },
+      );
+      emitTelemetry(telemetryClient, "installer_legacy_sibling_checkout_completed", {
+        release_tag: releaseTag,
+        os: target.os,
+        arch: target.arch,
+        repository: repoName,
+      });
+    } catch (error) {
+      emitTelemetry(telemetryClient, "installer_legacy_sibling_checkout_failed", {
+        release_tag: releaseTag,
+        os: target.os,
+        arch: target.arch,
+        repository: repoName,
+        ...telemetryFailureContext(error, "legacy_sibling_checkout"),
+      });
+      throw error;
+    }
+  }
+}
+
 function rustInstallCommand() {
   return "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y";
 }
@@ -713,6 +932,7 @@ async function ensureRustToolchain({
   fetchImpl,
   runProcessImpl,
   onStatus,
+  telemetryClient,
   promptImpl = promptForApproval,
   commandExistsImpl = commandExists,
   env = process.env,
@@ -725,44 +945,70 @@ async function ensureRustToolchain({
     return toolchainEnv;
   }
 
+  emitTelemetry(telemetryClient, "installer_rust_missing", {
+    os: target.os,
+    arch: target.arch,
+  });
+
   emitStatus(
     onStatus,
     "Rust toolchain required for source build",
     `${target.os}-${target.arch}`,
   );
 
+  emitTelemetry(telemetryClient, "installer_rust_install_prompt_shown", {
+    os: target.os,
+    arch: target.arch,
+  });
   const approved = await promptImpl(
     `Rust is required to build Pylon from source for ${target.os}-${target.arch}. Install the official Rust toolchain now via rustup?`,
   );
   if (!approved) {
+    emitTelemetry(telemetryClient, "installer_rust_install_declined", {
+      os: target.os,
+      arch: target.arch,
+    });
     throw new Error(
       `Rust is required to build Pylon from source.\nInstall it manually and rerun:\n${rustInstallCommand()}`,
     );
   }
 
-  emitStatus(onStatus, "Installing Rust toolchain", "official rustup installer");
-  const scriptPayload = await fetchText(fetchImpl, rustupInitUrl, {
-    headers: {
-      accept: "text/plain",
-      "user-agent": "@openagentsinc/pylon bootstrap",
-    },
-    runProcessImpl,
-    onStatus,
-    stage: "Rust toolchain installer download",
+  emitTelemetry(telemetryClient, "installer_rust_install_approved", {
+    os: target.os,
+    arch: target.arch,
   });
-  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "pylon-rustup-"));
-  const scriptPath = path.join(tempDir, "rustup-init.sh");
 
+  emitStatus(onStatus, "Installing Rust toolchain", "official rustup installer");
   try {
+    const scriptPayload = await fetchText(fetchImpl, rustupInitUrl, {
+      headers: {
+        accept: "text/plain",
+        "user-agent": "@openagentsinc/pylon bootstrap",
+      },
+      runProcessImpl,
+      onStatus,
+      stage: "Rust toolchain installer download",
+    });
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "pylon-rustup-"));
+    const scriptPath = path.join(tempDir, "rustup-init.sh");
     await fs.writeFile(scriptPath, scriptPayload);
     await fs.chmod(scriptPath, 0o755);
-    await runProcessImpl("sh", [scriptPath, "-y"], {
-      cwd: tempDir,
-      env: toolchainEnv,
-      stdio: "inherit",
+    try {
+      await runProcessImpl("sh", [scriptPath, "-y"], {
+        cwd: tempDir,
+        env: toolchainEnv,
+        stdio: "inherit",
+      });
+    } finally {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+  } catch (error) {
+    emitTelemetry(telemetryClient, "installer_rust_install_failed", {
+      os: target.os,
+      arch: target.arch,
+      ...telemetryFailureContext(error, "rust_install"),
     });
-  } finally {
-    await fs.rm(tempDir, { recursive: true, force: true });
+    throw error;
   }
 
   toolchainEnv = withPrependedPath(env, path.join(os.homedir(), ".cargo", "bin"));
@@ -779,6 +1025,10 @@ async function ensureRustToolchain({
     "Rust toolchain installed",
     path.join(os.homedir(), ".cargo", "bin"),
   );
+  emitTelemetry(telemetryClient, "installer_rust_install_completed", {
+    os: target.os,
+    arch: target.arch,
+  });
   return toolchainEnv;
 }
 
@@ -793,6 +1043,7 @@ async function installSourceBuild(
     fetchImpl,
     runProcessImpl,
     onStatus,
+    telemetryClient,
     promptImpl = promptForApproval,
     commandExistsImpl = commandExists,
   },
@@ -812,6 +1063,13 @@ async function installSourceBuild(
     "Prebuilt asset missing; falling back to source build",
     `${selected.tagName} for ${target.os}-${target.arch}`,
   );
+  emitTelemetry(telemetryClient, "installer_prebuilt_asset_missing", {
+    release_tag: selected.tagName,
+    release_commit: selected.targetCommitish ?? null,
+    os: target.os,
+    arch: target.arch,
+    platform_key: `${target.os}-${target.arch}`,
+  });
 
   if (!(await commandExistsImpl("git", process.env))) {
     throw new Error(
@@ -824,6 +1082,7 @@ async function installSourceBuild(
     fetchImpl,
     runProcessImpl,
     onStatus,
+    telemetryClient,
     promptImpl,
     commandExistsImpl,
   });
@@ -872,6 +1131,15 @@ async function installSourceBuild(
         env: buildEnv,
       },
     );
+    await hydrateLegacySiblingRepositories({
+      repoDir,
+      buildEnv,
+      runProcessImpl,
+      onStatus,
+      telemetryClient,
+      releaseTag: selected.tagName,
+      target,
+    });
 
     const { stdout: commitStdout } = await runProcessImpl(
       "git",
@@ -897,6 +1165,13 @@ async function installSourceBuild(
       "Building Pylon from source",
       `${selected.tagName} (${sourceCommit.slice(0, 12)})`,
     );
+    emitTelemetry(telemetryClient, "installer_source_build_started", {
+      release_tag: selected.tagName,
+      release_commit: sourceCommit,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+    });
     await runProcessImpl(buildCommand[0], buildCommand.slice(1), {
       cwd: repoDir,
       env: buildEnv,
@@ -938,6 +1213,17 @@ async function installSourceBuild(
       "Installed source-built binaries",
       `${selected.tagName} for ${target.os}-${target.arch}`,
     );
+    emitTelemetry(telemetryClient, "installer_source_build_completed", {
+      release_tag: selected.tagName,
+      release_commit: sourceCommit,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      install_source: installSourceForTelemetry(
+        SOURCE_BUILD_INSTALL_METHOD,
+        false,
+      ),
+    });
 
     return {
       ...selected,
@@ -950,6 +1236,14 @@ async function installSourceBuild(
       sourceCommit,
     };
   } catch (error) {
+    emitTelemetry(telemetryClient, "installer_source_build_failed", {
+      release_tag: selected.tagName,
+      release_commit: selected.targetCommitish ?? null,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      ...telemetryFailureContext(error, "source_build"),
+    });
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(
       `${message}\nManual source-build fallback:\n${manualBuildInstructions}`,
@@ -1013,6 +1307,9 @@ async function findLatestCachedInstall(installRoot, target) {
         pylonTuiPath,
         expectedSha256: manifest.sha256 ?? null,
         cached: true,
+        installMethod: manifest.installMethod ?? RELEASE_ASSET_INSTALL_METHOD,
+        sourceCloneUrl: manifest.sourceCloneUrl ?? null,
+        sourceCommit: manifest.sourceCommit ?? null,
         mtimeMs: manifestStat.mtimeMs,
       });
     } catch {
@@ -1124,6 +1421,7 @@ export async function ensureReleaseInstall(
     fetchImpl = globalThis.fetch,
     runProcessImpl = runProcess,
     onStatus = null,
+    telemetryClient = null,
     promptImpl = promptForApproval,
     commandExistsImpl = commandExists,
   } = {},
@@ -1141,25 +1439,38 @@ export async function ensureReleaseInstall(
   const installRoot = options.installRoot ?? defaultInstallRoot();
   if (options.version) {
     const requestedPaths = buildInstallPaths(installRoot, options.version, target);
+    const requestedManifest = await readInstallManifest(requestedPaths.manifestPath);
     const requestedCached =
       (await pathExists(requestedPaths.pylonPath)) &&
       (await pathExists(requestedPaths.pylonTuiPath));
     if (requestedCached) {
+      const installMethod =
+        requestedManifest?.installMethod ?? RELEASE_ASSET_INSTALL_METHOD;
       emitStatus(
         onStatus,
-        "Using cached standalone binaries",
+        installMethod === SOURCE_BUILD_INSTALL_METHOD
+          ? "Using cached source-built binaries"
+          : "Using cached standalone binaries",
         `pylon-v${normalizeVersion(options.version)} for ${target.os}-${target.arch}`,
       );
+      emitTelemetry(telemetryClient, "installer_cached_install_reused", {
+        release_tag: `pylon-v${normalizeVersion(options.version)}`,
+        release_commit: requestedManifest?.sourceCommit ?? null,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+        install_source: installSourceForTelemetry(installMethod, true),
+      });
       return {
         version: normalizeVersion(options.version),
         tagName: `pylon-v${normalizeVersion(options.version)}`,
         target,
         ...requestedPaths,
-        expectedSha256: await fs
-          .readFile(requestedPaths.manifestPath, "utf8")
-          .then((payload) => JSON.parse(payload).sha256)
-          .catch(() => null),
+        expectedSha256: requestedManifest?.sha256 ?? null,
         cached: true,
+        installMethod,
+        sourceCloneUrl: requestedManifest?.sourceCloneUrl ?? null,
+        sourceCommit: requestedManifest?.sourceCommit ?? null,
       };
     }
   }
@@ -1174,6 +1485,14 @@ export async function ensureReleaseInstall(
       apiBase: options.apiBase ?? DEFAULT_RELEASE_API_BASE,
       repo: options.repo ?? DEFAULT_RELEASE_REPO,
       version: options.version ?? null,
+      target,
+    });
+    emitTelemetry(telemetryClient, "installer_release_resolved", {
+      release_tag: release?.tag_name ?? null,
+      release_commit: release?.target_commitish ?? null,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
     });
   } catch (error) {
     const cached = !options.version
@@ -1182,9 +1501,19 @@ export async function ensureReleaseInstall(
     if (cached) {
       emitStatus(
         onStatus,
-        "Using cached standalone binaries",
+        cached.installMethod === SOURCE_BUILD_INSTALL_METHOD
+          ? "Using cached source-built binaries"
+          : "Using cached standalone binaries",
         `release lookup failed; falling back to ${cached.tagName}`,
       );
+      emitTelemetry(telemetryClient, "installer_cached_install_reused", {
+        release_tag: cached.tagName,
+        release_commit: cached.sourceCommit ?? null,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+        install_source: installSourceForTelemetry(cached.installMethod, true),
+      });
       return cached;
     }
 
@@ -1205,6 +1534,14 @@ export async function ensureReleaseInstall(
   let missingAssetsError = null;
   try {
     selected = selectReleaseAssets(release, target);
+    emitTelemetry(telemetryClient, "installer_prebuilt_asset_found", {
+      release_tag: selected.tagName,
+      release_commit: release?.target_commitish ?? null,
+      asset_name: selected.archiveAsset.name,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+    });
   } catch (error) {
     if (!(error instanceof MissingReleaseAssetsError)) {
       throw error;
@@ -1235,6 +1572,14 @@ export async function ensureReleaseInstall(
         : "Using cached standalone binaries",
       `${selected.tagName} for ${target.os}-${target.arch}`,
     );
+    emitTelemetry(telemetryClient, "installer_cached_install_reused", {
+      release_tag: selected.tagName,
+      release_commit: manifest?.sourceCommit ?? release?.target_commitish ?? null,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      install_source: installSourceForTelemetry(installMethod, true),
+    });
     return {
       ...selected,
       ...paths,
@@ -1259,6 +1604,7 @@ export async function ensureReleaseInstall(
         fetchImpl,
         runProcessImpl,
         onStatus,
+        telemetryClient,
         promptImpl,
         commandExistsImpl,
       },
@@ -1293,20 +1639,62 @@ export async function ensureReleaseInstall(
       "Downloading standalone binaries",
       selected.archiveAsset.name,
     );
-    await downloadFile(fetchImpl, selected.archiveAsset.url, paths.archivePath, {
-      runProcessImpl,
-      onStatus,
-      verbose: Boolean(options.verbose),
-      stage: "Release archive download",
+    emitTelemetry(telemetryClient, "installer_prebuilt_download_started", {
+      release_tag: selected.tagName,
+      asset_name: selected.archiveAsset.name,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
     });
+    try {
+      await downloadFile(fetchImpl, selected.archiveAsset.url, paths.archivePath, {
+        runProcessImpl,
+        onStatus,
+        verbose: Boolean(options.verbose),
+        stage: "Release archive download",
+      });
+      emitTelemetry(telemetryClient, "installer_prebuilt_download_completed", {
+        release_tag: selected.tagName,
+        asset_name: selected.archiveAsset.name,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+      });
+    } catch (error) {
+      emitTelemetry(telemetryClient, "installer_prebuilt_download_failed", {
+        release_tag: selected.tagName,
+        asset_name: selected.archiveAsset.name,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+        ...telemetryFailureContext(error, "prebuilt_download"),
+      });
+      throw error;
+    }
   }
 
   const actualSha256 = await sha256File(paths.archivePath);
   if (actualSha256 !== expectedSha256) {
+    emitTelemetry(telemetryClient, "installer_checksum_failed", {
+      release_tag: selected.tagName,
+      asset_name: selected.archiveAsset.name,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      error_stage: "checksum_verify",
+      error_code: "sha256_mismatch",
+    });
     throw new Error(
       `SHA-256 verification failed for ${selected.archiveAsset.name}: expected ${expectedSha256}, got ${actualSha256}.`,
     );
   }
+  emitTelemetry(telemetryClient, "installer_checksum_verified", {
+    release_tag: selected.tagName,
+    asset_name: selected.archiveAsset.name,
+    os: target.os,
+    arch: target.arch,
+    platform_key: `${target.os}-${target.arch}`,
+  });
 
   emitStatus(
     onStatus,
@@ -1348,6 +1736,9 @@ export async function ensureReleaseInstall(
     target,
     expectedSha256,
     cached: false,
+    installMethod: RELEASE_ASSET_INSTALL_METHOD,
+    sourceCloneUrl: null,
+    sourceCommit: null,
   };
 }
 
@@ -1356,6 +1747,7 @@ export async function bootstrapInstalledPylon(
   {
     runProcessImpl = runProcess,
     onStatus = null,
+    telemetryClient = null,
   } = {},
 ) {
   const pylonPath = path.resolve(options.pylonPath);
@@ -1365,125 +1757,176 @@ export async function bootstrapInstalledPylon(
     options.diagnosticRepeats ?? DEFAULT_DIAGNOSTIC_REPEATS;
   const diagnosticMaxOutputTokens =
     options.diagnosticMaxOutputTokens ?? DEFAULT_DIAGNOSTIC_MAX_OUTPUT_TOKENS;
+  emitTelemetry(telemetryClient, "installer_smoke_test_started", {
+    release_tag: options.tagName ?? `pylon-v${options.version}`,
+    release_commit: options.sourceCommit ?? null,
+    os: options.target?.os ?? null,
+    arch: options.target?.arch ?? null,
+    platform_key:
+      options.target?.os && options.target?.arch
+        ? `${options.target.os}-${options.target.arch}`
+        : null,
+    install_source: installSourceForTelemetry(
+      options.installMethod,
+      Boolean(options.cached),
+    ),
+  });
 
-  emitStatus(onStatus, "Verifying Pylon binary", path.basename(pylonPath));
-  await runPylonCommand(pylonPath, ["--help"], options, runProcessImpl);
-  emitStatus(onStatus, "Bootstrapping local Pylon identity");
-  const init = await runPylonJson(pylonPath, ["init"], options, runProcessImpl);
-  emitStatus(onStatus, "Checking runtime health");
-  const status = await runPylonJson(
-    pylonPath,
-    ["status", "--json"],
-    options,
-    runProcessImpl,
-  );
-  emitStatus(onStatus, "Scanning for local models");
-  const inventory = await runPylonJson(
-    pylonPath,
-    ["inventory", "--json"],
-    options,
-    runProcessImpl,
-  );
-
-  let download = null;
-  if (!options.skipModelDownload) {
-    emitStatus(onStatus, "Downloading curated model bundle", model);
-    download = await runPylonJson(
+  try {
+    emitStatus(onStatus, "Verifying Pylon binary", path.basename(pylonPath));
+    await runPylonCommand(pylonPath, ["--help"], options, runProcessImpl);
+    emitStatus(onStatus, "Bootstrapping local Pylon identity");
+    const init = await runPylonJson(pylonPath, ["init"], options, runProcessImpl);
+    emitStatus(onStatus, "Checking runtime health");
+    const status = await runPylonJson(
       pylonPath,
-      ["gemma", "download", model, "--json"],
+      ["status", "--json"],
       options,
       runProcessImpl,
     );
-  } else {
-    emitStatus(
-      onStatus,
-      "Skipping optional curated GGUF cache",
-      "use --download-curated-cache to prefetch Hugging Face weights",
+    emitStatus(onStatus, "Scanning for local models");
+    const inventory = await runPylonJson(
+      pylonPath,
+      ["inventory", "--json"],
+      options,
+      runProcessImpl,
     );
-  }
 
-  let diagnostic = null;
-  if (!options.skipDiagnostics) {
-    emitStatus(onStatus, "Running first-run diagnostic", model);
-    try {
-      diagnostic = await runPylonJson(
+    let download = null;
+    if (!options.skipModelDownload) {
+      emitStatus(onStatus, "Downloading curated model bundle", model);
+      download = await runPylonJson(
         pylonPath,
-        [
-          "gemma",
-          "diagnose",
-          model,
-          "--max-output-tokens",
-          String(diagnosticMaxOutputTokens),
-          "--repeats",
-          String(diagnosticRepeats),
-          "--json",
-        ],
+        ["gemma", "download", model, "--json"],
         options,
         runProcessImpl,
       );
-    } catch (error) {
-      if (!isUnsupportedGemmaDiagnoseError(error)) {
-        throw error;
-      }
+    } else {
       emitStatus(
         onStatus,
-        "Skipping first-run diagnostic",
-        "installed Pylon release does not expose gemma diagnose",
+        "Skipping optional curated GGUF cache",
+        "use --download-curated-cache to prefetch Hugging Face weights",
       );
     }
-  } else {
-    emitStatus(onStatus, "Skipping first-run diagnostic", model);
-  }
 
-  const diagnosticResult =
-    diagnostic?.results?.find((result) => result.model_id === model) ??
-    diagnostic?.results?.[0] ??
-    null;
+    let diagnostic = null;
+    if (!options.skipDiagnostics) {
+      emitStatus(onStatus, "Running first-run diagnostic", model);
+      try {
+        diagnostic = await runPylonJson(
+          pylonPath,
+          [
+            "gemma",
+            "diagnose",
+            model,
+            "--max-output-tokens",
+            String(diagnosticMaxOutputTokens),
+            "--repeats",
+            String(diagnosticRepeats),
+            "--json",
+          ],
+          options,
+          runProcessImpl,
+        );
+      } catch (error) {
+        if (!isUnsupportedGemmaDiagnoseError(error)) {
+          throw error;
+        }
+        emitStatus(
+          onStatus,
+          "Skipping first-run diagnostic",
+          "installed Pylon release does not expose gemma diagnose",
+        );
+      }
+    } else {
+      emitStatus(onStatus, "Skipping first-run diagnostic", model);
+    }
 
-  emitStatus(
-    onStatus,
-    "Bootstrap complete",
-    diagnosticResult?.status
-      ? `diagnostic ${diagnosticResult.status}`
-      : "smoke path complete",
-  );
+    const diagnosticResult =
+      diagnostic?.results?.find((result) => result.model_id === model) ??
+      diagnostic?.results?.[0] ??
+      null;
 
-  return {
-    version: options.version,
-    tagName: options.tagName ?? `pylon-v${options.version}`,
-    target: options.target,
-    cached: Boolean(options.cached),
-    binaries: {
-      pylon: pylonPath,
-      pylonTui: pylonTuiPath,
-    },
-    configPath: init?.config_path ?? options.configPath ?? null,
-    pylonHome: options.pylonHome ? path.resolve(options.pylonHome) : null,
-    init,
-    status,
-    inventory,
-    model,
-    download,
-    diagnostic,
-    diagnosticResult,
-  };
+    emitStatus(
+      onStatus,
+      "Bootstrap complete",
+      diagnosticResult?.status
+        ? `diagnostic ${diagnosticResult.status}`
+        : "smoke path complete",
+    );
+    emitTelemetry(telemetryClient, "installer_smoke_test_completed", {
+      release_tag: options.tagName ?? `pylon-v${options.version}`,
+      release_commit: options.sourceCommit ?? null,
+      os: options.target?.os ?? null,
+      arch: options.target?.arch ?? null,
+      platform_key:
+        options.target?.os && options.target?.arch
+          ? `${options.target.os}-${options.target.arch}`
+          : null,
+      install_source: installSourceForTelemetry(
+        options.installMethod,
+        Boolean(options.cached),
+      ),
+      diagnostic_status: diagnosticResult?.status ?? null,
+    });
+
+    return {
+      version: options.version,
+      tagName: options.tagName ?? `pylon-v${options.version}`,
+      target: options.target,
+      cached: Boolean(options.cached),
+      installMethod: options.installMethod ?? RELEASE_ASSET_INSTALL_METHOD,
+      binaries: {
+        pylon: pylonPath,
+        pylonTui: pylonTuiPath,
+      },
+      configPath: init?.config_path ?? options.configPath ?? null,
+      pylonHome: options.pylonHome ? path.resolve(options.pylonHome) : null,
+      init,
+      status,
+      inventory,
+      model,
+      download,
+      diagnostic,
+      diagnosticResult,
+    };
+  } catch (error) {
+    emitTelemetry(telemetryClient, "installer_smoke_test_failed", {
+      release_tag: options.tagName ?? `pylon-v${options.version}`,
+      release_commit: options.sourceCommit ?? null,
+      os: options.target?.os ?? null,
+      arch: options.target?.arch ?? null,
+      platform_key:
+        options.target?.os && options.target?.arch
+          ? `${options.target.os}-${options.target.arch}`
+          : null,
+      install_source: installSourceForTelemetry(
+        options.installMethod,
+        Boolean(options.cached),
+      ),
+      ...telemetryFailureContext(error, "smoke_test"),
+    });
+    throw error;
+  }
 }
 
-export async function launchInstalledPylonTui(
+export async function launchInstalledPylon(
   options,
   {
     runProcessImpl = runProcess,
     onStatus = null,
   } = {},
 ) {
-  const pylonTuiPath = path.resolve(options.pylonTuiPath);
-  emitStatus(onStatus, "Opening Pylon terminal UI", path.basename(pylonTuiPath));
-  return runProcessImpl(pylonTuiPath, [], {
+  const pylonPath = path.resolve(options.pylonPath);
+  emitStatus(onStatus, "Starting Pylon default earning loop", path.basename(pylonPath));
+  return runProcessImpl(pylonPath, [], {
     env: buildPylonEnv(options),
     stdio: "inherit",
   });
 }
 
+export const launchInstalledPylonTui = launchInstalledPylon;
+
 export function resolveBootstrapOutcome(summary) {
   const runtimeState =
     summary.status?.snapshot?.runtime?.authoritative_status ?? "unknown";
@@ -1546,7 +1989,7 @@ function renderBootstrapNextSteps(summary, outcome) {
   ];
 
   if (outcome.verdict === "fully online" || outcome.verdict === "runtime ready") {
-    lines.push("Next step: open the TUI with `pylon`, or keep using the package-managed launcher.");
+    lines.push("Next step: run `pylon`; it starts the default online earning loop.");
     return lines;
   }
 
@@ -1572,6 +2015,7 @@ export function renderBootstrapSummary(summary) {
     `Verdict detail: ${outcome.detail}`,
     `Pylon release: ${summary.version} (${summary.target.os}-${summary.target.arch})`,
     `Archive source: ${summary.tagName}`,
+    `Install source: ${installSourceForTelemetry(summary.installMethod, summary.cached).replaceAll("_", " ")}`,
     `Installed from cache: ${summary.cached ? "yes" : "no"}`,
     `Pylon binary: ${summary.binaries.pylon}`,
     `Pylon TUI: ${summary.binaries.pylonTui}`,