@xortex/xcode 3.0.0

package/utils/plugins/cacheUtils.ts

@@ -0,0 +1,196 @@
+import { readdir, rm, stat, unlink, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { clearCommandsCache } from '../../commands.js'
+import { clearAllOutputStylesCache } from '../../constants/outputStyles.js'
+import { clearAgentDefinitionsCache } from '../../tools/AgentTool/loadAgentsDir.js'
+import { clearPromptCache } from '../../tools/SkillTool/prompt.js'
+import { resetSentSkillNames } from '../attachments.js'
+import { logForDebugging } from '../debug.js'
+import { getErrnoCode } from '../errors.js'
+import { logError } from '../log.js'
+import { loadInstalledPluginsFromDisk } from './installedPluginsManager.js'
+import { clearPluginAgentCache } from './loadPluginAgents.js'
+import { clearPluginCommandCache } from './loadPluginCommands.js'
+import {
+  clearPluginHookCache,
+  pruneRemovedPluginHooks,
+} from './loadPluginHooks.js'
+import { clearPluginOutputStyleCache } from './loadPluginOutputStyles.js'
+import { clearPluginCache, getPluginCachePath } from './pluginLoader.js'
+import { clearPluginOptionsCache } from './pluginOptionsStorage.js'
+import { isPluginZipCacheEnabled } from './zipCache.js'
+
+const ORPHANED_AT_FILENAME = '.orphaned_at'
+const CLEANUP_AGE_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+
+export function clearAllPluginCaches(): void {
+  clearPluginCache()
+  clearPluginCommandCache()
+  clearPluginAgentCache()
+  clearPluginHookCache()
+  // Prune hooks from plugins no longer in the enabled set so uninstalled/
+  // disabled plugins stop firing immediately (gh-36995). Prune-only: hooks
+  // from newly-enabled plugins are NOT added here — they wait for
+  // /reload-plugins like commands/agents/MCP do. Fire-and-forget: old hooks
+  // stay valid until the prune completes (preserves gh-29767). No-op when
+  // STATE.registeredHooks is empty (test/preload.ts beforeEach clears it via
+  // resetStateForTests before reaching here).
+  pruneRemovedPluginHooks().catch(e => logError(e))
+  clearPluginOptionsCache()
+  clearPluginOutputStyleCache()
+  clearAllOutputStylesCache()
+}
+
+export function clearAllCaches(): void {
+  clearAllPluginCaches()
+  clearCommandsCache()
+  clearAgentDefinitionsCache()
+  clearPromptCache()
+  resetSentSkillNames()
+}
+
+/**
+ * Mark a plugin version as orphaned.
+ * Called when a plugin is uninstalled or updated to a new version.
+ */
+export async function markPluginVersionOrphaned(
+  versionPath: string,
+): Promise<void> {
+  try {
+    await writeFile(getOrphanedAtPath(versionPath), `${Date.now()}`, 'utf-8')
+  } catch (error) {
+    logForDebugging(`Failed to write .orphaned_at: ${versionPath}: ${error}`)
+  }
+}
+
+/**
+ * Clean up orphaned plugin versions that have been orphaned for more than 7 days.
+ *
+ * Pass 1: Remove .orphaned_at from installed versions (clears stale markers)
+ * Pass 2: For each cached version not in installed_plugins.json:
+ *   - If no .orphaned_at exists: create it (handles old CC versions, manual edits)
+ *   - If .orphaned_at exists and > 7 days old: delete the version
+ */
+export async function cleanupOrphanedPluginVersionsInBackground(): Promise<void> {
+  // Zip cache mode stores plugins as .zip files, not directories. readSubdirs
+  // filters to directories only, so removeIfEmpty would see plugin dirs as empty
+  // and delete them (including the ZIPs). Skip cleanup entirely in zip mode.
+  if (isPluginZipCacheEnabled()) {
+    return
+  }
+  try {
+    const installedVersions = getInstalledVersionPaths()
+    if (!installedVersions) return
+
+    const cachePath = getPluginCachePath()
+
+    const now = Date.now()
+
+    // Pass 1: Remove .orphaned_at from installed versions
+    // This handles cases where a plugin was reinstalled after being orphaned
+    await Promise.all(
+      [...installedVersions].map(p => removeOrphanedAtMarker(p)),
+    )
+
+    // Pass 2: Process orphaned versions
+    for (const marketplace of await readSubdirs(cachePath)) {
+      const marketplacePath = join(cachePath, marketplace)
+
+      for (const plugin of await readSubdirs(marketplacePath)) {
+        const pluginPath = join(marketplacePath, plugin)
+
+        for (const version of await readSubdirs(pluginPath)) {
+          const versionPath = join(pluginPath, version)
+          if (installedVersions.has(versionPath)) continue
+          await processOrphanedPluginVersion(versionPath, now)
+        }
+
+        await removeIfEmpty(pluginPath)
+      }
+
+      await removeIfEmpty(marketplacePath)
+    }
+  } catch (error) {
+    logForDebugging(`Plugin cache cleanup failed: ${error}`)
+  }
+}
+
+function getOrphanedAtPath(versionPath: string): string {
+  return join(versionPath, ORPHANED_AT_FILENAME)
+}
+
+async function removeOrphanedAtMarker(versionPath: string): Promise<void> {
+  const orphanedAtPath = getOrphanedAtPath(versionPath)
+  try {
+    await unlink(orphanedAtPath)
+  } catch (error) {
+    const code = getErrnoCode(error)
+    if (code === 'ENOENT') return
+    logForDebugging(`Failed to remove .orphaned_at: ${versionPath}: ${error}`)
+  }
+}
+
+function getInstalledVersionPaths(): Set<string> | null {
+  try {
+    const paths = new Set<string>()
+    const diskData = loadInstalledPluginsFromDisk()
+    for (const installations of Object.values(diskData.plugins)) {
+      for (const entry of installations) {
+        paths.add(entry.installPath)
+      }
+    }
+    return paths
+  } catch (error) {
+    logForDebugging(`Failed to load installed plugins: ${error}`)
+    return null
+  }
+}
+
+async function processOrphanedPluginVersion(
+  versionPath: string,
+  now: number,
+): Promise<void> {
+  const orphanedAtPath = getOrphanedAtPath(versionPath)
+
+  let orphanedAt: number
+  try {
+    orphanedAt = (await stat(orphanedAtPath)).mtimeMs
+  } catch (error) {
+    const code = getErrnoCode(error)
+    if (code === 'ENOENT') {
+      await markPluginVersionOrphaned(versionPath)
+      return
+    }
+    logForDebugging(`Failed to stat orphaned marker: ${versionPath}: ${error}`)
+    return
+  }
+
+  if (now - orphanedAt > CLEANUP_AGE_MS) {
+    try {
+      await rm(versionPath, { recursive: true, force: true })
+    } catch (error) {
+      logForDebugging(
+        `Failed to delete orphaned version: ${versionPath}: ${error}`,
+      )
+    }
+  }
+}
+
+async function removeIfEmpty(dirPath: string): Promise<void> {
+  if ((await readSubdirs(dirPath)).length === 0) {
+    try {
+      await rm(dirPath, { recursive: true, force: true })
+    } catch (error) {
+      logForDebugging(`Failed to remove empty dir: ${dirPath}: ${error}`)
+    }
+  }
+}
+
+async function readSubdirs(dirPath: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true })
+    return entries.filter(d => d.isDirectory()).map(d => d.name)
+  } catch {
+    return []
+  }
+}

package/utils/plugins/dependencyResolver.ts

@@ -0,0 +1,305 @@
+/**
+ * Plugin dependency resolution — pure functions, no I/O.
+ *
+ * Semantics are `apt`-style: a dependency is a *presence guarantee*, not a
+ * module graph. Plugin A depending on Plugin B means "B's namespaced
+ * components (MCP servers, commands, agents) must be available when A runs."
+ *
+ * Two entry points:
+ *  - `resolveDependencyClosure` — install-time DFS walk, cycle detection
+ *  - `verifyAndDemote` — load-time fixed-point check, demotes plugins with
+ *    unsatisfied deps (session-local, does NOT write settings)
+ */
+
+import type { LoadedPlugin, PluginError } from '../../types/plugin.js'
+import type { EditableSettingSource } from '../settings/constants.js'
+import { getSettingsForSource } from '../settings/settings.js'
+import { parsePluginIdentifier } from './pluginIdentifier.js'
+import type { PluginId } from './schemas.js'
+
+/**
+ * Synthetic marketplace sentinel for `--plugin-dir` plugins (pluginLoader.ts
+ * sets `source = "{name}@inline"`). Not a real marketplace — bare deps from
+ * these plugins cannot meaningfully inherit it.
+ */
+const INLINE_MARKETPLACE = 'inline'
+
+/**
+ * Normalize a dependency reference to fully-qualified "name@marketplace" form.
+ * Bare names (no @) inherit the marketplace of the plugin declaring them —
+ * cross-marketplace deps are blocked anyway, so the @-suffix is boilerplate
+ * in the common case.
+ *
+ * EXCEPTION: if the declaring plugin is @inline (loaded via --plugin-dir),
+ * bare deps are returned unchanged. `inline` is a synthetic sentinel, not a
+ * real marketplace — fabricating "dep@inline" would never match anything.
+ * verifyAndDemote handles bare deps via name-only matching.
+ */
+export function qualifyDependency(
+  dep: string,
+  declaringPluginId: string,
+): string {
+  if (parsePluginIdentifier(dep).marketplace) return dep
+  const mkt = parsePluginIdentifier(declaringPluginId).marketplace
+  if (!mkt || mkt === INLINE_MARKETPLACE) return dep
+  return `${dep}@${mkt}`
+}
+
+/**
+ * Minimal shape the resolver needs from a marketplace lookup. Keeping this
+ * narrow means the resolver stays testable without constructing full
+ * PluginMarketplaceEntry objects.
+ */
+export type DependencyLookupResult = {
+  // Entries may be bare names; qualifyDependency normalizes them.
+  dependencies?: string[]
+}
+
+export type ResolutionResult =
+  | { ok: true; closure: PluginId[] }
+  | { ok: false; reason: 'cycle'; chain: PluginId[] }
+  | { ok: false; reason: 'not-found'; missing: PluginId; requiredBy: PluginId }
+  | {
+      ok: false
+      reason: 'cross-marketplace'
+      dependency: PluginId
+      requiredBy: PluginId
+    }
+
+/**
+ * Walk the transitive dependency closure of `rootId` via DFS.
+ *
+ * The returned `closure` ALWAYS contains `rootId`, plus every transitive
+ * dependency that is NOT in `alreadyEnabled`. Already-enabled deps are
+ * skipped (not recursed into) — this avoids surprise settings writes when a
+ * dep is already installed at a different scope. The root is never skipped,
+ * even if already enabled, so re-installing a plugin always re-caches it.
+ *
+ * Cross-marketplace dependencies are BLOCKED by default: a plugin in
+ * marketplace A cannot auto-install a plugin from marketplace B. This is
+ * a security boundary — installing from a trusted marketplace shouldn't
+ * silently pull from an untrusted one. Two escapes: (1) install the
+ * cross-mkt dep yourself first (already-enabled deps are skipped, so the
+ * closure won't touch it), or (2) the ROOT marketplace's
+ * `allowCrossMarketplaceDependenciesOn` allowlist — only the root's list
+ * applies for the whole walk (no transitive trust: if A allows B, B's
+ * plugin depending on C is still blocked unless A also allows C).
+ *
+ * @param rootId Root plugin to resolve from (format: "name@marketplace")
+ * @param lookup Async lookup returning `{dependencies}` or `null` if not found
+ * @param alreadyEnabled Plugin IDs to skip (deps only, root is never skipped)
+ * @param allowedCrossMarketplaces Marketplace names the root trusts for
+ *   auto-install (from the root marketplace's manifest)
+ * @returns Closure to install, or a cycle/not-found/cross-marketplace error
+ */
+export async function resolveDependencyClosure(
+  rootId: PluginId,
+  lookup: (id: PluginId) => Promise<DependencyLookupResult | null>,
+  alreadyEnabled: ReadonlySet<PluginId>,
+  allowedCrossMarketplaces: ReadonlySet<string> = new Set(),
+): Promise<ResolutionResult> {
+  const rootMarketplace = parsePluginIdentifier(rootId).marketplace
+  const closure: PluginId[] = []
+  const visited = new Set<PluginId>()
+  const stack: PluginId[] = []
+
+  async function walk(
+    id: PluginId,
+    requiredBy: PluginId,
+  ): Promise<ResolutionResult | null> {
+    // Skip already-enabled DEPENDENCIES (avoids surprise settings writes),
+    // but NEVER skip the root: installing an already-enabled plugin must
+    // still cache/register it. Without this guard, re-installing a plugin
+    // that's in settings but missing from disk (e.g., cache cleared,
+    // installed_plugins.json stale) would return an empty closure and
+    // `cacheAndRegisterPlugin` would never fire — user sees
+    // "✔ Successfully installed" but nothing materializes.
+    if (id !== rootId && alreadyEnabled.has(id)) return null
+    // Security: block auto-install across marketplace boundaries. Runs AFTER
+    // the alreadyEnabled check — if the user manually installed a cross-mkt
+    // dep, it's in alreadyEnabled and we never reach this.
+    const idMarketplace = parsePluginIdentifier(id).marketplace
+    if (
+      idMarketplace !== rootMarketplace &&
+      !(idMarketplace && allowedCrossMarketplaces.has(idMarketplace))
+    ) {
+      return {
+        ok: false,
+        reason: 'cross-marketplace',
+        dependency: id,
+        requiredBy,
+      }
+    }
+    if (stack.includes(id)) {
+      return { ok: false, reason: 'cycle', chain: [...stack, id] }
+    }
+    if (visited.has(id)) return null
+    visited.add(id)
+
+    const entry = await lookup(id)
+    if (!entry) {
+      return { ok: false, reason: 'not-found', missing: id, requiredBy }
+    }
+
+    stack.push(id)
+    for (const rawDep of entry.dependencies ?? []) {
+      const dep = qualifyDependency(rawDep, id)
+      const err = await walk(dep, id)
+      if (err) return err
+    }
+    stack.pop()
+
+    closure.push(id)
+    return null
+  }
+
+  const err = await walk(rootId, rootId)
+  if (err) return err
+  return { ok: true, closure }
+}
+
+/**
+ * Load-time safety net: for each enabled plugin, verify all manifest
+ * dependencies are also in the enabled set. Demote any that fail.
+ *
+ * Fixed-point loop: demoting plugin A may break plugin B that depends on A,
+ * so we iterate until nothing changes.
+ *
+ * The `reason` field distinguishes:
+ *  - `'not-enabled'` — dep exists in the loaded set but is disabled
+ *  - `'not-found'` — dep is entirely absent (not in any marketplace)
+ *
+ * Does NOT mutate input. Returns the set of plugin IDs (sources) to demote.
+ *
+ * @param plugins All loaded plugins (enabled + disabled)
+ * @returns Set of pluginIds to demote, plus errors for `/doctor`
+ */
+export function verifyAndDemote(plugins: readonly LoadedPlugin[]): {
+  demoted: Set<string>
+  errors: PluginError[]
+} {
+  const known = new Set(plugins.map(p => p.source))
+  const enabled = new Set(plugins.filter(p => p.enabled).map(p => p.source))
+  // Name-only indexes for bare deps from --plugin-dir (@inline) plugins:
+  // the real marketplace is unknown, so match "B" against any enabled "B@*".
+  // enabledByName is a multiset: if B@epic AND B@other are both enabled,
+  // demoting one mustn't make "B" disappear from the index.
+  const knownByName = new Set(
+    plugins.map(p => parsePluginIdentifier(p.source).name),
+  )
+  const enabledByName = new Map<string, number>()
+  for (const id of enabled) {
+    const n = parsePluginIdentifier(id).name
+    enabledByName.set(n, (enabledByName.get(n) ?? 0) + 1)
+  }
+  const errors: PluginError[] = []
+
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const p of plugins) {
+      if (!enabled.has(p.source)) continue
+      for (const rawDep of p.manifest.dependencies ?? []) {
+        const dep = qualifyDependency(rawDep, p.source)
+        // Bare dep ← @inline plugin: match by name only (see enabledByName)
+        const isBare = !parsePluginIdentifier(dep).marketplace
+        const satisfied = isBare
+          ? (enabledByName.get(dep) ?? 0) > 0
+          : enabled.has(dep)
+        if (!satisfied) {
+          enabled.delete(p.source)
+          const count = enabledByName.get(p.name) ?? 0
+          if (count <= 1) enabledByName.delete(p.name)
+          else enabledByName.set(p.name, count - 1)
+          errors.push({
+            type: 'dependency-unsatisfied',
+            source: p.source,
+            plugin: p.name,
+            dependency: dep,
+            reason: (isBare ? knownByName.has(dep) : known.has(dep))
+              ? 'not-enabled'
+              : 'not-found',
+          })
+          changed = true
+          break
+        }
+      }
+    }
+  }
+
+  const demoted = new Set(
+    plugins.filter(p => p.enabled && !enabled.has(p.source)).map(p => p.source),
+  )
+  return { demoted, errors }
+}
+
+/**
+ * Find all enabled plugins that declare `pluginId` as a dependency.
+ * Used to warn on uninstall/disable ("required by: X, Y").
+ *
+ * @param pluginId The plugin being removed/disabled
+ * @param plugins All loaded plugins (only enabled ones are checked)
+ * @returns Names of plugins that will break if `pluginId` goes away
+ */
+export function findReverseDependents(
+  pluginId: PluginId,
+  plugins: readonly LoadedPlugin[],
+): string[] {
+  const { name: targetName } = parsePluginIdentifier(pluginId)
+  return plugins
+    .filter(
+      p =>
+        p.enabled &&
+        p.source !== pluginId &&
+        (p.manifest.dependencies ?? []).some(d => {
+          const qualified = qualifyDependency(d, p.source)
+          // Bare dep (from @inline plugin): match by name only
+          return parsePluginIdentifier(qualified).marketplace
+            ? qualified === pluginId
+            : qualified === targetName
+        }),
+    )
+    .map(p => p.name)
+}
+
+/**
+ * Build the set of plugin IDs currently enabled at a given settings scope.
+ * Used by install-time resolution to skip already-enabled deps and avoid
+ * surprise settings writes.
+ *
+ * Matches `true` (plain enable) AND array values (version constraints per
+ * settings/types.ts:455-463 — a plugin at `"foo@bar": ["^1.0.0"]` IS enabled).
+ * Without the array check, a version-pinned dep would be re-added to the
+ * closure and the settings write would clobber the constraint with `true`.
+ */
+export function getEnabledPluginIdsForScope(
+  settingSource: EditableSettingSource,
+): Set<PluginId> {
+  return new Set(
+    Object.entries(getSettingsForSource(settingSource)?.enabledPlugins ?? {})
+      .filter(([, v]) => v === true || Array.isArray(v))
+      .map(([k]) => k),
+  )
+}
+
+/**
+ * Format the "(+ N dependencies)" suffix for install success messages.
+ * Returns empty string when `installedDeps` is empty.
+ */
+export function formatDependencyCountSuffix(installedDeps: string[]): string {
+  if (installedDeps.length === 0) return ''
+  const n = installedDeps.length
+  return ` (+ ${n} ${n === 1 ? 'dependency' : 'dependencies'})`
+}
+
+/**
+ * Format the "warning: required by X, Y" suffix for uninstall/disable
+ * results. Em-dash style for CLI result messages (not the middot style
+ * used in the notification UI). Returns empty string when no dependents.
+ */
+export function formatReverseDependentsSuffix(
+  rdeps: string[] | undefined,
+): string {
+  if (!rdeps || rdeps.length === 0) return ''
+  return ` — warning: required by ${rdeps.join(', ')}`
+}

package/utils/plugins/fetchTelemetry.ts

@@ -0,0 +1,135 @@
+/**
+ * Telemetry for plugin/marketplace fetches that hit the network.
+ *
+ * Added for inc-5046 (GitHub complained about claude-plugins-official load).
+ * Before this, fetch operations only had logForDebugging — no way to measure
+ * actual network volume. This surfaces what's hitting GitHub vs GCS vs
+ * user-hosted so we can see the GCS migration take effect and catch future
+ * hot-path regressions before GitHub emails us again.
+ *
+ * Volume: these fire at startup (install-counts 24h-TTL)
+ * and on explicit user action (install/update). NOT per-interaction. Similar
+ * envelope to tengu_binary_download_*.
+ */
+
+import {
+  logEvent,
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS as SafeString,
+} from '../../services/analytics/index.js'
+import { OFFICIAL_MARKETPLACE_NAME } from './officialMarketplace.js'
+
+export type PluginFetchSource =
+  | 'install_counts'
+  | 'marketplace_clone'
+  | 'marketplace_pull'
+  | 'marketplace_url'
+  | 'plugin_clone'
+  | 'mcpb'
+
+export type PluginFetchOutcome = 'success' | 'failure' | 'cache_hit'
+
+// Allowlist of public hosts we report by name. Anything else (enterprise
+// git, self-hosted, internal) is bucketed as 'other' — we don't want
+// internal hostnames (git.mycorp.internal) landing in telemetry. Bounded
+// cardinality also keeps the dashboard host-breakdown tractable.
+const KNOWN_PUBLIC_HOSTS = new Set([
+  'github.com',
+  'raw.githubusercontent.com',
+  'objects.githubusercontent.com',
+  'gist.githubusercontent.com',
+  'gitlab.com',
+  'bitbucket.org',
+  'codeberg.org',
+  'dev.azure.com',
+  'ssh.dev.azure.com',
+  'storage.googleapis.com', // GCS — where Dickson's migration points
+])
+
+/**
+ * Extract hostname from a URL or git spec and bucket to the allowlist.
+ * Handles `https://host/...`, `git@host:path`, `ssh://host/...`.
+ * Returns a known public host, 'other' (parseable but not allowlisted —
+ * don't leak private hostnames), or 'unknown' (unparseable / local path).
+ */
+function extractHost(urlOrSpec: string): string {
+  let host: string
+  const scpMatch = /^[^@/]+@([^:/]+):/.exec(urlOrSpec)
+  if (scpMatch) {
+    host = scpMatch[1]!
+  } else {
+    try {
+      host = new URL(urlOrSpec).hostname
+    } catch {
+      return 'unknown'
+    }
+  }
+  const normalized = host.toLowerCase()
+  return KNOWN_PUBLIC_HOSTS.has(normalized) ? normalized : 'other'
+}
+
+/**
+ * True if the URL/spec points at anthropics/claude-plugins-official — the
+ * repo GitHub complained about. Lets the dashboard separate "our problem"
+ * traffic from user-configured marketplaces.
+ */
+function isOfficialRepo(urlOrSpec: string): boolean {
+  return urlOrSpec.includes(`anthropics/${OFFICIAL_MARKETPLACE_NAME}`)
+}
+
+export function logPluginFetch(
+  source: PluginFetchSource,
+  urlOrSpec: string | undefined,
+  outcome: PluginFetchOutcome,
+  durationMs: number,
+  errorKind?: string,
+): void {
+  // String values are bounded enums / hostname-only — no code, no paths,
+  // no raw error messages. Same privacy envelope as tengu_web_fetch_host.
+  logEvent('tengu_plugin_remote_fetch', {
+    source: source as SafeString,
+    host: (urlOrSpec ? extractHost(urlOrSpec) : 'unknown') as SafeString,
+    is_official: urlOrSpec ? isOfficialRepo(urlOrSpec) : false,
+    outcome: outcome as SafeString,
+    duration_ms: Math.round(durationMs),
+    ...(errorKind && { error_kind: errorKind as SafeString }),
+  })
+}
+
+/**
+ * Classify an error into a stable bucket for the error_kind field. Keeps
+ * cardinality bounded — raw error messages would explode dashboard grouping.
+ *
+ * Handles both axios Error objects (Node.js error codes like ENOTFOUND) and
+ * git stderr strings (human phrases like "Could not resolve host"). DNS
+ * checked BEFORE timeout because gitClone's error enhancement at
+ * marketplaceManager.ts:~950 rewrites DNS failures to include the word
+ * "timeout" — ordering the other way would misclassify git DNS as timeout.
+ */
+export function classifyFetchError(error: unknown): string {
+  const msg = String((error as { message?: unknown })?.message ?? error)
+  if (
+    /ENOTFOUND|ECONNREFUSED|EAI_AGAIN|Could not resolve host|Connection refused/i.test(
+      msg,
+    )
+  ) {
+    return 'dns_or_refused'
+  }
+  if (/ETIMEDOUT|timed out|timeout/i.test(msg)) return 'timeout'
+  if (
+    /ECONNRESET|socket hang up|Connection reset by peer|remote end hung up/i.test(
+      msg,
+    )
+  ) {
+    return 'conn_reset'
+  }
+  if (/403|401|authentication|permission denied/i.test(msg)) return 'auth'
+  if (/404|not found|repository not found/i.test(msg)) return 'not_found'
+  if (/certificate|SSL|TLS|unable to get local issuer/i.test(msg)) return 'tls'
+  // Schema validation throws "Invalid response format" (install_counts) —
+  // distinguish from true unknowns so the dashboard can
+  // see "server sent garbage" separately.
+  if (/Invalid response format|Invalid marketplace schema/i.test(msg)) {
+    return 'invalid_schema'
+  }
+  return 'other'
+}