@sandgarden/gloria 0.0.0-stage → 0.3.88

package/collector/stub.sh

@@ -0,0 +1,463 @@
+#!/bin/sh
+# gloria collector download stub
+# (docs/plans/2026-08-21-collector-shell-bootstrap-design.md, superseding the
+#  node stub of docs/plans/2026-07-10-collector-binary-distribution-design.md)
+#
+# This single self-contained file ships verbatim into the published plugin as
+# plugins/<name>/collector/stub.sh. It is POSIX `sh` on purpose: every plugin
+# hook command is ALREADY a shell-form string that Claude Code evaluates with
+# `sh -c` on macOS/Linux and Git Bash on Windows, so `sh` is not a new
+# prerequisite — it is what runs the hook line today. The previous stub was
+# node, which made a JS runtime a hard host requirement and silently disabled
+# usage tracking on machines without one (#761).
+#
+# It downloads the compiled collector binary for this platform once per build
+# version from the published repo's GitHub Release, verifies it against the
+# SHA-256 checksums stamped below at publish time, caches it under the
+# collector's state directory (`bin/`), and runs it with argv + stdin passed
+# through, mirroring its exit code.
+#
+# Contract (it runs inside the agent loop, like the hooks it fronts):
+# - ANY failure — offline, GitHub down, unsupported platform, checksum
+#   mismatch, no curl, no hashing tool — logs ONE line to the state
+#   directory's collector.log and exits 0. The next hook fire retries. It must
+#   never break an agent session.
+# - Checksum mismatch NEVER executes the downloaded bytes: the stamped
+#   checksums are the trust anchor (a substituted release asset fails closed),
+#   and unverified bytes are deleted rather than renamed into the cache.
+# - GLORIA_COLLECTOR_BIN=<path> bypasses download entirely (local builds,
+#   air-gapped installs, corp mirrors).
+#
+# Host tools: sh, curl, and one of sha256sum / shasum / openssl / certutil,
+# plus the usual coreutils. There is deliberately no wget fallback: wget cannot
+# report the effective final URL, so a wget path would silently drop the
+# final-host allowlist below.
+
+# Stamped by scripts/publish-marketplace/stage.mjs (run by
+# .github/workflows/publish-marketplace.yml) at publish time — the source tree
+# always carries the placeholder values (same mechanism as check-version.mjs's
+# INSTALLED_VERSION). Each placeholder appears exactly once so the workflow's
+# sed + grep verification can't miss.
+#
+# RELEASE_REPO and ASSET_PREFIX are stamped at publish time
+# (scripts/publish-marketplace/stage.mjs): every plugin that bundles this stub
+# now downloads the same release from "sandgardenhq/plugins" with the
+# "miranda-collector" prefix (#813). They stay placeholders rather than
+# literals so the release host can move without editing this file.
+BUILD_VERSION="81ca1fa7a45e"
+RELEASE_TAG="collector-81ca1fa7a45e"
+RELEASE_REPO="sandgardenhq/plugins"
+ASSET_PREFIX="miranda-collector"
+CHECKSUM_DARWIN_ARM64="93d0a631dfb5d6446254f2a78133d2eba9f007855acfc7889f7f94e9349abd08"
+CHECKSUM_DARWIN_X64="bb8d3cd150f965c6c338411accfbd604c0b2fbce44974770ccc79b3526c8a9b7"
+CHECKSUM_LINUX_X64="fd7cd2a516515b4250e7501beac3e53b856556bf4c4fb07eb691d8af922f563d"
+CHECKSUM_LINUX_ARM64="ecc2f57a8c7568b9d3ba951b6ec2eb0bff56da72d95a87b30d90f5ac022f8b54"
+CHECKSUM_WINDOWS_X64="24bda878b843b6fa7dbf2784fde4947c26191ccff71d1569f9293a2766ec5f46"
+
+# A download lock older than this is a downloader that died mid-run: take it
+# over (mirrors the collector's sweep-lock staleness cutoff).
+LOCK_STALE_MINUTES=10
+# A *.download-* temp older than this is a download that was SIGKILLed
+# mid-write (the cleanup never ran): safe to sweep — a live download finishes
+# in well under an hour or its lock has long gone stale.
+DOWNLOAD_TEMP_STALE_MINUTES=60
+LOG_MAX_BYTES=1048576
+CURL_MAX_SECONDS=600
+
+# What `hook-session-start` tells the agent when no collector could be handed
+# to it (#1568). The binary is the thing that is missing, so nothing downstream
+# can say so; this is the one place that can. The wording is a copy of
+# COLLECTOR_NOT_INSTALLED_NUDGE in hooks.ts (a test pins the two together) and
+# of the fallback in the Miranda plugin's hooks.json. No quote characters in the
+# text, so it needs no JSON escaping here.
+NOT_INSTALLED_NUDGE='{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"The usage collector is not installed or could not be set up on this machine, so no token usage is being recorded. Tell the user now: reinstall or update the Miranda plugin and start a new session; the cause is logged in collector.log under ~/.config/sandgarden."}}'
+
+# The pre-#783 state directory, kept only as a migration source.
+LEGACY_HOME_DIR_NAME=".gloria"
+
+# Shells expand a leading "~" before we ever see it — hook configs and env
+# files don't, so we have to.
+expand_tilde() {
+  case "$1" in
+    "~/"*) printf '%s' "$HOME/${1#\~/}" ;;
+    *) printf '%s' "$1" ;;
+  esac
+}
+
+# The explicit full-path override in effect; returns 1 (printing nothing) when
+# there is none. GLORIA_HOME is the deprecated alias of SANDGARDEN_HOME — it
+# names one of the two products sharing this directory, which is exactly what
+# #783 fixes, but a user who set it deliberately chose that path and must not
+# have their state silently relocated. Empty reads as unset.
+home_override() {
+  if [ -n "${SANDGARDEN_HOME-}" ]; then
+    expand_tilde "$SANDGARDEN_HOME"
+    return 0
+  fi
+  if [ -n "${GLORIA_HOME-}" ]; then
+    expand_tilde "$GLORIA_HOME"
+    return 0
+  fi
+  return 1
+}
+
+# Mirrors state.ts's collectorHome(), which this file has to duplicate rather
+# than share: the directory must be resolved before the binary that would
+# resolve it exists. Precedence:
+#   SANDGARDEN_HOME | GLORIA_HOME | $XDG_CONFIG_HOME/sandgarden | ~/.config/sandgarden
+collector_home() {
+  if ch_override="$(home_override)"; then
+    printf '%s' "$ch_override"
+    return 0
+  fi
+  if [ -n "${XDG_CONFIG_HOME-}" ]; then
+    printf '%s/sandgarden' "$(expand_tilde "$XDG_CONFIG_HOME")"
+  else
+    printf '%s/.config/sandgarden' "$HOME"
+  fi
+}
+
+# Append one line to the state directory's collector.log (rotating once past
+# 1 MB, like the collector's own logger). Logging must never fail — exit 0
+# still holds.
+log_error() {
+  le_home="$(collector_home)"
+  mkdir -p "$le_home" 2>/dev/null || return 0
+  le_log="$le_home/collector.log"
+  if [ -f "$le_log" ]; then
+    le_size="$(wc -c <"$le_log" 2>/dev/null | tr -d ' ')"
+    case "$le_size" in
+      '' | *[!0-9]*) le_size=0 ;;
+    esac
+    if [ "$le_size" -gt "$LOG_MAX_BYTES" ]; then
+      mv -f "$le_log" "$le_log.1" 2>/dev/null || : # rename overwrites the old .1
+    fi
+  fi
+  le_stamp="$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null)"
+  printf '%s collector-stub error: %s\n' "$le_stamp" "$1" >>"$le_log" 2>/dev/null || :
+  return 0
+}
+
+# Map uname's platform/arch to the release asset. Sets ASSET_KEY, ASSET_EXT and
+# ASSET_NAME; returns 1 (leaving the pair in PLATFORM_LABEL) when unsupported.
+# MINGW/MSYS/CYGWIN are how Git Bash — the shell Claude Code runs hooks in on
+# Windows — reports itself.
+resolve_asset() {
+  ra_sys="$(uname -s 2>/dev/null || printf 'unknown')"
+  ra_machine="$(uname -m 2>/dev/null || printf 'unknown')"
+  case "$ra_sys" in
+    Darwin) ra_platform=darwin ;;
+    Linux) ra_platform=linux ;;
+    MINGW* | MSYS* | CYGWIN* | Windows_NT) ra_platform=windows ;;
+    *) ra_platform="$ra_sys" ;;
+  esac
+  case "$ra_machine" in
+    arm64 | aarch64) ra_arch=arm64 ;;
+    x86_64 | amd64) ra_arch=x64 ;;
+    *) ra_arch="$ra_machine" ;;
+  esac
+  PLATFORM_LABEL="$ra_platform-$ra_arch"
+  ASSET_EXT=""
+  case "$PLATFORM_LABEL" in
+    darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64) ASSET_KEY="$PLATFORM_LABEL" ;;
+    windows-x64)
+      ASSET_KEY="windows-x64"
+      ASSET_EXT=".exe"
+      ;;
+    *) return 1 ;;
+  esac
+  ASSET_NAME="$ASSET_PREFIX-$ASSET_KEY$ASSET_EXT"
+  return 0
+}
+
+# The stamped checksum for an asset key. POSIX sh has no associative arrays,
+# and one variable per platform is also what keeps every checksum placeholder
+# appearing exactly once for the publish workflow's sed (which has no /g, and
+# whose grep verification would otherwise pass on a half-stamped file).
+checksum_for() {
+  case "$1" in
+    darwin-arm64) printf '%s' "$CHECKSUM_DARWIN_ARM64" ;;
+    darwin-x64) printf '%s' "$CHECKSUM_DARWIN_X64" ;;
+    linux-x64) printf '%s' "$CHECKSUM_LINUX_X64" ;;
+    linux-arm64) printf '%s' "$CHECKSUM_LINUX_ARM64" ;;
+    windows-x64) printf '%s' "$CHECKSUM_WINDOWS_X64" ;;
+  esac
+}
+
+# Lowercase hex SHA-256 of a file, using whichever tool this host has.
+# certutil is the Windows built-in fallback for a Git Bash without coreutils.
+# Returns 1 (and prints nothing) when the host has NO usable tool, which the
+# caller reports differently from a tool that ran and failed.
+sha256_of() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" 2>/dev/null | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" 2>/dev/null | awk '{print $1}'
+  elif command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 "$1" 2>/dev/null | awk '{print $NF}'
+  elif command -v certutil >/dev/null 2>&1; then
+    certutil -hashfile "$1" SHA256 2>/dev/null | sed -n '2p' | tr -d ' \r' | tr 'A-F' 'a-f'
+  else
+    return 1
+  fi
+}
+
+# Print the not-installed nudge, for `hook-session-start` only — the one hook
+# whose stdout reaches the agent's context. Every other subcommand stays quiet.
+# Under `--enrolled-only` (#1566, the gloria plugin) it also stays quiet unless
+# this machine has a config.json: "reinstall the Miranda plugin" is a Miranda
+# prompt, and gloria must never show one to someone who never opted in. Only
+# existence is checked — the binary that could validate the file is the thing
+# that is missing. Always returns 0: the exit-0 contract above still holds.
+nudge_not_installed() {
+  [ "${1-}" = "hook-session-start" ] || return 0
+  for ni_arg in "$@"; do
+    if [ "$ni_arg" = "--enrolled-only" ]; then
+      [ -f "$(collector_home)/config.json" ] || return 0
+    fi
+  done
+  printf '%s\n' "$NOT_INSTALLED_NUDGE"
+  return 0
+}
+
+# Take the download lock. `mkdir` is the portable atomic create-or-fail. A LIVE
+# lock (younger than LOCK_STALE_MINUTES) returns 1 — the loser exits 0 and lets
+# the winner finish. A stale lock is taken over by rename, not by rm: exactly
+# one contender can win a rename, whereas an rm-based takeover would let a
+# loser delete the winner's freshly-created lock. Mirrors the collector's
+# acquireSweepLock.
+acquire_download_lock() {
+  al_lock="$1"
+  al_attempt=0
+  while [ "$al_attempt" -lt 3 ]; do
+    al_attempt=$((al_attempt + 1))
+    if mkdir "$al_lock" 2>/dev/null; then
+      return 0
+    fi
+    # `find -mmin` is absent only on exotic finds; when it can't tell, the lock
+    # reads as live and this run defers — the next hook fire retries.
+    if [ -z "$(find "$al_lock" -maxdepth 0 -mmin "+$LOCK_STALE_MINUTES" 2>/dev/null)" ]; then
+      return 1
+    fi
+    al_takeover="$al_lock.takeover-$$-$al_attempt"
+    if mv "$al_lock" "$al_takeover" 2>/dev/null; then
+      rm -rf "$al_takeover" 2>/dev/null || :
+      continue
+    fi
+    # The holder released it between our mkdir and our rename: retry the mkdir.
+    [ -e "$al_lock" ] || continue
+    return 1 # another contender won the takeover rename first
+  done
+  return 1
+}
+
+# Reuse the binary a pre-#783 install already cached under ~/.gloria/bin,
+# instead of re-downloading it (#783) — an offline machine has to keep working
+# across the rename. Returns 0 when $1 is ready to execute.
+#
+# Only THIS copy's own stamped asset name is considered, so an entry cached by
+# a differently-stamped stub sharing the legacy bin/ (gloria's and Miranda's
+# plugins both installed) is left exactly where its owner expects it. Copy
+# rather than move, for the same reason: a sibling plugin that hasn't updated
+# yet may still be running from it. Skipped when the directory was pinned
+# explicitly — that path was chosen deliberately. Best-effort and silent: any
+# failure just falls through to the normal download.
+migrate_cached_binary() {
+  mcb_bin="$1"
+  home_override >/dev/null && return 1
+  mcb_legacy="$HOME/$LEGACY_HOME_DIR_NAME/bin/${mcb_bin##*/}"
+  [ -f "$mcb_legacy" ] || return 1
+  mkdir -p "${mcb_bin%/*}" 2>/dev/null || return 1
+  mcb_tmp="$mcb_bin.migrate-$$"
+  if cp "$mcb_legacy" "$mcb_tmp" 2>/dev/null &&
+    chmod 755 "$mcb_tmp" 2>/dev/null &&
+    mv -f "$mcb_tmp" "$mcb_bin" 2>/dev/null; then # atomic: no partial file is ever executed
+    return 0
+  fi
+  rm -f "$mcb_tmp" 2>/dev/null || :
+  return 1
+}
+
+# Download the asset to a temp file, verify its SHA-256 against the stamped
+# checksum, then atomically rename into place. Returns 0 when $1 is ready to
+# execute; 1 (after logging) otherwise, or 2 on a silent lock deferral. The
+# temp file and the lock are always cleaned up, and unverified bytes are never
+# left executable at the cache path.
+download_binary() {
+  db_bin="$1"
+  db_dir="${db_bin%/*}"
+  if ! mkdir -p "$db_dir" 2>/dev/null; then
+    log_error "cannot create cache directory $db_dir"
+    return 1
+  fi
+  db_lock="$db_dir/.download.lock"
+  if ! acquire_download_lock "$db_lock"; then
+    return 2 # a concurrent session is downloading — silently defer, no nudge
+  fi
+  db_tmp="$db_bin.download-$$-$(date -u '+%s' 2>/dev/null || printf '0')"
+  db_expected="$(checksum_for "$ASSET_KEY")"
+  db_url="https://github.com/$RELEASE_REPO/releases/download/$RELEASE_TAG/$ASSET_NAME"
+  db_status=1
+
+  if ! command -v curl >/dev/null 2>&1; then
+    log_error "curl not found; cannot download $ASSET_NAME"
+  else
+    # --proto/--proto-redir '=https' refuse a plain-http hop outright rather
+    # than letting one be detected after the bytes have already moved;
+    # --fail turns HTTP >= 400 into a non-zero exit; --write-out reports the
+    # URL the transfer actually landed on, for the host allowlist below.
+    db_effective="$(
+      curl --fail --location --silent \
+        --proto '=https' --proto-redir '=https' \
+        --max-redirs 5 --max-time "$CURL_MAX_SECONDS" \
+        --write-out '%{url_effective}' \
+        --output "$db_tmp" "$db_url" 2>/dev/null
+    )"
+    db_curl_status=$?
+    if [ "$db_curl_status" -ne 0 ]; then
+      log_error "download of $ASSET_NAME failed: curl exit $db_curl_status"
+    else
+      # GitHub redirects release-asset downloads to a GitHub-owned object
+      # host; it serves them from both objects. and release-assets.. Requiring
+      # a literal "/" after the host is what makes github.com.evil.example
+      # fail to match. Defense-in-depth on top of the checksum.
+      case "$db_effective" in
+        https://github.com/* | https://objects.githubusercontent.com/* | https://release-assets.githubusercontent.com/*)
+          db_host_ok=yes
+          ;;
+        *) db_host_ok=no ;;
+      esac
+      if [ "$db_host_ok" = no ]; then
+        log_error "download resolved to disallowed URL $db_effective; refusing"
+      elif [ ! -s "$db_tmp" ]; then
+        log_error "download of $ASSET_NAME returned no body"
+      elif ! db_actual="$(sha256_of "$db_tmp")"; then
+        log_error "no SHA-256 tool found (sha256sum, shasum, openssl, or certutil); refusing to execute $ASSET_NAME"
+      elif [ -z "$db_actual" ]; then
+        log_error "failed to compute the SHA-256 of $ASSET_NAME; refusing to execute"
+      elif [ "$db_actual" != "$db_expected" ]; then
+        log_error "checksum mismatch for $ASSET_NAME: expected $db_expected, got $db_actual; refusing to execute"
+      elif ! chmod 755 "$db_tmp" 2>/dev/null; then
+        log_error "cannot make $ASSET_NAME executable; refusing to install"
+      elif ! mv -f "$db_tmp" "$db_bin" 2>/dev/null; then
+        # atomic: readers never see a partial file
+        log_error "cannot install $ASSET_NAME into $db_bin"
+      else
+        db_status=0
+      fi
+    fi
+  fi
+
+  rm -f "$db_tmp" 2>/dev/null || : # no-op after a successful rename
+  rm -rf "$db_lock" 2>/dev/null || :
+  return "$db_status"
+}
+
+# Run the collector binary with argv + stdin passed through and echo its exit
+# code. Not `exec`, because the cache still has to be pruned afterwards.
+# 126/127 are the shell's "couldn't execute that" codes — the equivalent of the
+# node stub's spawn `error` event — so they log and become 0 rather than
+# leaking out as a hook failure. The collector itself only ever exits 0 or 1.
+run_binary() {
+  rb_bin="$1"
+  shift
+  if [ ! -x "$rb_bin" ]; then
+    log_error "spawn of $rb_bin failed: not executable"
+    nudge_not_installed "$@"
+    return 0
+  fi
+  "$rb_bin" "$@"
+  rb_status=$?
+  if [ "$rb_status" -eq 126 ] || [ "$rb_status" -eq 127 ]; then
+    log_error "spawn of $rb_bin failed: exit $rb_status"
+    nudge_not_installed "$@"
+    return 0
+  fi
+  return "$rb_status"
+}
+
+# Delete cached collector binaries beyond the 2 most recent (by mtime), never
+# the one just run, plus any stranded *.download-* temp file older than an
+# hour. Best-effort: pruning must not fail the hook. Only files carrying THIS
+# copy's stamped asset prefix are considered, so a binary cached by a
+# differently-stamped copy sharing the same bin/ (e.g. gloria's and Miranda's
+# plugins both installed) is never touched.
+prune_cache() {
+  pc_dir="$1"
+  pc_keep="$2"
+  [ -d "$pc_dir" ] || return 0
+  find "$pc_dir" -maxdepth 1 \( -name '*.download-*' -o -name '*.migrate-*' \) \
+    -mmin "+$DOWNLOAD_TEMP_STALE_MINUTES" -exec rm -f {} + 2>/dev/null || :
+  pc_kept=0
+  # Cache entries are <prefix>-<hex> — no whitespace — so word splitting on
+  # `ls -t` (newest first) is safe here, and it is the portable way to get
+  # mtime order without a second sort tool.
+  # shellcheck disable=SC2045
+  for pc_name in $(ls -t "$pc_dir" 2>/dev/null); do
+    case "$pc_name" in
+      "$ASSET_PREFIX-"*) ;;
+      *) continue ;;
+    esac
+    case "$pc_name" in
+      *.download-* | *.migrate-*) continue ;;
+    esac
+    if [ "$pc_kept" -lt 2 ]; then
+      pc_kept=$((pc_kept + 1))
+      continue
+    fi
+    pc_path="$pc_dir/$pc_name"
+    [ "$pc_path" = "$pc_keep" ] && continue
+    rm -f "$pc_path" 2>/dev/null || :
+  done
+  return 0
+}
+
+# The whole stub: override | unstamped | resolve → (cache | download+verify) →
+# run → prune. Every failure path exits 0.
+main() {
+  if [ -n "${GLORIA_COLLECTOR_BIN-}" ]; then
+    if [ ! -x "$GLORIA_COLLECTOR_BIN" ]; then
+      log_error "GLORIA_COLLECTOR_BIN=$GLORIA_COLLECTOR_BIN is not an executable file; skipping"
+      exit 0
+    fi
+    # Nothing to prune on this path, so exec straight through: argv, stdin and
+    # the exit code all pass to the override untouched.
+    exec "$GLORIA_COLLECTOR_BIN" "$@"
+  fi
+
+  # Dev tree: the publish workflow never stamped this copy (the placeholders
+  # are still in place). Local dev runs `bun src/cli.ts …` or sets
+  # GLORIA_COLLECTOR_BIN instead.
+  case "$BUILD_VERSION" in
+    __*)
+      log_error "stub is unstamped (dev checkout?); set GLORIA_COLLECTOR_BIN or install the published plugin"
+      exit 0
+      ;;
+  esac
+
+  if ! resolve_asset; then
+    log_error "unsupported platform $PLATFORM_LABEL; skipping"
+    nudge_not_installed "$@"
+    exit 0
+  fi
+
+  m_bin_dir="$(collector_home)/bin"
+  m_bin="$m_bin_dir/$ASSET_PREFIX-$BUILD_VERSION$ASSET_EXT"
+  if [ ! -f "$m_bin" ]; then
+    if ! migrate_cached_binary "$m_bin"; then
+      download_binary "$m_bin"
+      m_download=$?
+      if [ "$m_download" -ne 0 ]; then
+        # Logged inside. 2 is a lock deferral — the winner is installing it.
+        [ "$m_download" -eq 2 ] || nudge_not_installed "$@"
+        exit 0
+      fi
+    fi
+  fi
+  run_binary "$m_bin" "$@"
+  m_status=$?
+  prune_cache "$m_bin_dir" "$m_bin"
+  exit "$m_status"
+}
+
+main "$@"

package/gloria.js

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// Published as the npm package @sandgarden/gloria (#813): the bundled skills
+// and the collector download stub ship inside the package, beside this file —
+// scripts/publish-marketplace/stage.mjs assembles it. In the monorepo neither
+// exists here, so the skills path is empty and spawnCollector's existsSync
+// guard silently no-ops during local dev. #403: gloria and miranda each bundle
+// their own stub — a gloria-only install must still track usage.
+const skillsDir = path.resolve(__dirname, "skills")
+const collectorStubPath = path.resolve(__dirname, "collector/stub.sh")
+
+// Stamped at publish time by scripts/publish-marketplace/stage.mjs — the
+// source tree always reads "DEV", exactly like check-plugin-version's hook.
+const INSTALLED_VERSION = "0.3.88"
+const LATEST_VERSION_URL = "https://gloria.dev/api/plugin-version"
+
+// Local, dependency-free comparison for this repo's simple `x.y.z` versions
+// (no npm semver package is used anywhere in this repo). The unstamped "DEV"
+// placeholder (the source-tree value before publish-time stamping) always
+// compares as lower than any real version, so it always nudges.
+function compareVersions(a, b) {
+  if (a === "DEV" && b === "DEV") return 0
+  if (a === "DEV") return -1
+  if (b === "DEV") return 1
+
+  const partsA = a.split(".").map(Number)
+  const partsB = b.split(".").map(Number)
+  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0)
+    if (diff !== 0) return diff < 0 ? -1 : 1
+  }
+  return 0
+}
+
+export function formatVersionNudge(installedVersion, latestVersion) {
+  if (compareVersions(installedVersion, latestVersion) >= 0) return null
+  return `The gloria.dev plugin is out of date (installed ${installedVersion}, latest ${latestVersion}). Update it, then start a new session.`
+}
+
+/**
+ * Mutate an OpenCode config object to wire up gloria.dev: register the bundled
+ * skills directory and the remote gloria.dev MCP server. Idempotent and
+ * non-clobbering — a user-defined gloria MCP entry wins.
+ */
+export function applyGloriaConfig(config, dir = skillsDir) {
+  config.skills = config.skills || {}
+  config.skills.paths = config.skills.paths || []
+  if (!config.skills.paths.includes(dir)) config.skills.paths.push(dir)
+  config.mcp = config.mcp || {}
+  config.mcp.gloria = config.mcp.gloria || {
+    type: "remote",
+    url: "https://mcp.gloria.dev/mcp",
+    enabled: true,
+  }
+  return config
+}
+
+/**
+ * Fire-and-forget call into the collector, via the download stub.
+ *
+ * This runs IN-PROCESS with OpenCode (unlike Claude Code's spawned hook
+ * process), and a first run can download a ~50 MB collector binary — so the
+ * child is detached and unref'd rather than awaited, and every failure
+ * (missing stub, spawn error) is swallowed: a collector bug must never block
+ * or slow an OpenCode session.
+ *
+ * The stub is POSIX sh, not node (#761) — the collector must not require a
+ * JS runtime on the host. On Windows that needs `sh` on PATH (Git for
+ * Windows' Unix tools); without it the spawn errors and is swallowed, the
+ * same silent no-op a missing `node` produced before.
+ */
+function spawnCollector(args, spawnImpl, stubPath) {
+  try {
+    if (!fs.existsSync(stubPath)) return
+    const child = spawnImpl("sh", [stubPath, ...args], {
+      detached: true,
+      stdio: "ignore",
+    })
+    child.on("error", () => {})
+    child.unref()
+  } catch {
+    // Must never block or crash the session.
+  }
+}
+
+/**
+ * Session start: the same `hook-session-start` entrypoint Claude Code's
+ * SessionStart hook uses. Since #847 that entrypoint does not sweep — it makes
+ * sure this machine has a collector DAEMON, installing the per-user service
+ * the first time, and the daemon's own watcher on OpenCode's storage directory
+ * is what ingests the session.
+ *
+ * OpenCode keeps its sessions in SQLite rather than in a transcript file, so
+ * there is no path a spool trigger could name; the watcher is the whole of the
+ * handoff here.
+ */
+export function startCollectorSession(spawnImpl = spawn, stubPath = collectorStubPath) {
+  spawnCollector(["hook-session-start"], spawnImpl, stubPath)
+}
+
+/**
+ * Per-turn: `daemon ensure` and nothing else.
+ *
+ * `session.idle` fires once per TURN, and the session-start entrypoint above
+ * runs a whole bootstrap — a service-registration probe (a subprocess on Linux
+ * and Windows), a config load, the nudges. That is a session-start's worth of
+ * work to pay for every turn. All this handler actually owes the collector is
+ * "is a daemon up?", which is one lock-file read when the answer is yes.
+ */
+export function ensureCollectorDaemon(spawnImpl = spawn, stubPath = collectorStubPath) {
+  spawnCollector(["daemon", "ensure"], spawnImpl, stubPath)
+}
+
+// OpenCode plugin entry. The `config` hook receives OpenCode's config singleton;
+// mutations here are visible when skills and MCP servers are resolved later.
+// The `client` param is OpenCode's plugin client, used by the session.created
+// hook to surface a version nudge (see formatVersionNudge above). `spawnImpl`
+// and `stubPath` exist for test injection only — production callers never
+// pass them, so they default to the real child_process.spawn and the shared
+// collector stub path.
+export const gloria = async ({ client, spawnImpl = spawn, stubPath = collectorStubPath } = {}) => ({
+  config: async (config) => {
+    applyGloriaConfig(config)
+  },
+  "session.created": async () => {
+    startCollectorSession(spawnImpl, stubPath)
+    try {
+      const res = await fetch(LATEST_VERSION_URL)
+      if (!res.ok) return
+      const { latest } = await res.json()
+      const message = formatVersionNudge(INSTALLED_VERSION, latest)
+      if (message) await client?.app?.log({ service: "gloria", level: "warn", message })
+    } catch {
+      // Network hiccups must never block session start.
+    }
+  },
+  // Closest OpenCode analog to Claude Code's per-turn Stop hook: fires once
+  // the agent loop finishes a turn and is waiting on the user again. Cheap on
+  // purpose — see ensureCollectorDaemon.
+  "session.idle": async () => {
+    ensureCollectorDaemon(spawnImpl, stubPath)
+  },
+})
+
+export default gloria

package/index.js

@@ -0,0 +1 @@
+export { default } from "./gloria.js"

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@sandgarden/gloria",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.88",
+  "type": "module",
+  "description": "gloria.dev OpenCode plugin — dependency-discovery skills + the gloria.dev MCP server.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "gloria.js",
+    "skills",
+    "collector"
+  ],
+  "homepage": "https://gloria.dev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}