@sandgarden/miranda 0.0.0-stage → 0.1.75

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="a1f67fd00034"
+RELEASE_TAG="collector-a1f67fd00034"
+RELEASE_REPO="sandgardenhq/plugins"
+ASSET_PREFIX="miranda-collector"
+CHECKSUM_DARWIN_ARM64="6f45d8c3bc3140d834f80801da6898865cd5ee943f1d8baf9a9d29d2f4615d63"
+CHECKSUM_DARWIN_X64="040c2fb941b000703ea29e9712e33765445eaa91fc328f59bd113548e1e8e10d"
+CHECKSUM_LINUX_X64="a5d0a38637cb9ca3942ff16a4d19fef42865e2e0eaa9a80817895869222a613e"
+CHECKSUM_LINUX_ARM64="29c6ec818a15ae698ee421a2ef3b1d348711f55a64df10094d1a36d8cf43dca8"
+CHECKSUM_WINDOWS_X64="79acbbcdacf1c5f547015dd3ab58366acd8b99c195b5911520e49ca28967d369"
+
+# 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/index.js

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

package/miranda.js

@@ -0,0 +1,114 @@
+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/miranda (#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 spawnCollector's existsSync guard silently no-ops during
+// local dev.
+const skillsDir = path.resolve(__dirname, "skills")
+const collectorStubPath = path.resolve(__dirname, "collector/stub.sh")
+
+/**
+ * Mutate an OpenCode config object to wire up Miranda: register the bundled
+ * skills directory and the scoped /miranda MCP endpoint (identity + cost
+ * tools only — see packages/mcp/src/index.ts). Idempotent and
+ * non-clobbering — a user-defined miranda MCP entry wins.
+ */
+export function applyMirandaConfig(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.miranda = config.mcp.miranda || {
+    type: "remote",
+    url: "https://mcp.gloria.dev/miranda",
+    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. Unlike the gloria plugin, there is no session.created
+// version-nudge check — Miranda ships no version-nudge hook at all (mirrors
+// the doc-holiday precedent: no dedicated plugin-version endpoint to poll).
+// `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 miranda = async ({ spawnImpl = spawn, stubPath = collectorStubPath } = {}) => ({
+  config: async (config) => {
+    applyMirandaConfig(config)
+  },
+  "session.created": async () => {
+    startCollectorSession(spawnImpl, stubPath)
+  },
+  // 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 miranda

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@sandgarden/miranda",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.75",
+  "type": "module",
+  "description": "Miranda OpenCode plugin — token-usage tracking skill + the gloria.dev MCP server's scoped /miranda tools.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "miranda.js",
+    "skills",
+    "collector"
+  ],
+  "homepage": "https://miranda.co",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/setting-up-usage-tracking/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: setting-up-usage-tracking
+description: Use when installing the Miranda plugin into a repo ("set up token tracking", "enable usage tracking", "install miranda"), when a repo is missing .miranda/USING-MIRANDA.md or the miranda section in CLAUDE.md/AGENTS.md, or after a Miranda plugin update to refresh a stale doc — copies the canonical USING-MIRANDA.md agent doc into the repo, wires an evergreen Miranda section into the agent instruction files (with the user's permission), and enrols this machine for usage collection. Idempotent; safe to re-run.
+---
+
+# Setting Up Usage Tracking
+
+## Overview
+
+Wire Miranda into the current repo so every coding agent that works here
+declares the GitHub issue it's working on and this machine's token usage
+gets collected. Two files carry that:
+
+1. **`.miranda/USING-MIRANDA.md`** — the agent playbook, copied verbatim
+   from the `USING-MIRANDA.md` that sits next to this SKILL.md (the skill's
+   base directory). Committed to the repo.
+2. **A marked section in the repo's agent instruction files** (`CLAUDE.md`
+   and/or `AGENTS.md`) that points unconditionally at the doc. The section is
+   evergreen — it names no features, so it never changes across Miranda
+   releases; only the doc does.
+
+Then, once those are wired, enrol this machine so the collector daemon the
+Miranda plugin installs actually starts reporting usage.
+
+Never modify the user's files without showing them exactly what will change
+and getting a yes first.
+
+## What the collector reports
+
+Tell the user this when you propose enrolling a machine (step 2). It is what
+they are consenting to.
+
+- **Always:** token usage per model request (model, token counts,
+  timestamps, session and request ids), a random per-machine id, and this
+  machine's hostname, OS, and architecture. Never message content.
+- **Only if the organization turns it on:** the workflow events below.
+
+**Workflow events — off by default.** Your organization admin can turn workflow collection on for the whole organization in Miranda's settings; until they do, the collector reports token usage exactly as described here and nothing more. When it is on, the collector also reports the **structure, not content**, of each session it already reads: sizes, names, and flags, never a prompt, a reply, a file body, a tool's output, or a full shell command (only its first word and its class). These are the event kinds:
+
+- `session_start`: branch, repository, entrypoint; the directory as a hash
+- `session_end`: why it ended and how long it ran
+- `human_turn`: prompt size and slash-command name, never the prompt
+- `assistant_turn`: model, effort, stop reason and size, never the reply
+- `model_request`: the token counts already reported today
+- `tool_call`: tool name, argument names, repo-relative file path, and a shell command's first word only, plus the names of any wrappers a hook added to it before it ran (such as `rtk`)
+- `tool_result`: error flag, size, exit code and test counts, never the output
+- `project_facts`: manifest and instruction file names, sizes and hashes
+- `skill_invoked`: skill name and whether it came from a plugin, the project, or the user
+- `subagent_spawned`: subagent type, model override and whether it ran in the background, never its prompt
+- `plan_mode`: entering or leaving plan mode, never the plan
+- `compaction`: whether a context compaction was automatic or manual, and the context size before it
+- `vcs_event`: commit, push, PR create or merge, or rebase, with PR and issue numbers only, never a branch, message or remote
+- `hook_fired`: hook name, the first word of the hook's own command (such as `rtk`), and whether it blocked, never its arguments or output
+- `mcp_tool_call`: MCP server and tool name, never arguments or results
+
+## The instruction-file section
+
+Insert this text exactly, markers included. The markers are how re-runs find
+and replace the section instead of duplicating it.
+
+```markdown
+<!-- miranda:start -->
+
+## Miranda
+
+This project uses [Miranda](https://miranda.co) to track coding-agent
+token cost and attribute it to the GitHub issues the work was for.
+
+Before starting work in this repo, read `.miranda/USING-MIRANDA.md`. It
+explains the one thing required at the start of every session — declaring
+the work item — plus the Miranda MCP tools available to you. Treat it as a
+commitment the team has made, not a suggestion.
+
+<!-- miranda:end -->
+```
+
+## Workflow
+
+### 1. Detect state
+
+- Find the repo root (`git rev-parse --show-toplevel`; fall back to the
+  working directory if not a git repo).
+- Locate the shipped doc: the `USING-MIRANDA.md` in this skill's base
+  directory. If it is missing, stop and tell the user the plugin install
+  looks broken — do not synthesize the doc from memory.
+- Check what already exists at the repo root:
+  - `.miranda/USING-MIRANDA.md` — present?
+  - `CLAUDE.md`, `AGENTS.md` — which exist, and does each already contain a
+    `<!-- miranda:start -->` ... `<!-- miranda:end -->` block?
+  - **Is this machine already enrolled?** Look for the collector's
+    `config.json`, in **both** places, in this order:
+
+    1. `$XDG_CONFIG_HOME/sandgarden/config.json`, defaulting to
+       `~/.config/sandgarden/config.json` when `XDG_CONFIG_HOME` is unset;
+    2. `~/.gloria/config.json` — the pre-rename location. A machine set up
+       before the rename still has its credential here; the collector
+       migrates it automatically on its next run, so this counts as
+       "already enabled" too.
+
+    Either one present means usage tracking is already on for this machine
+    (per-machine, not per-repo) and step 5 is a no-op — say so rather than
+    re-minting a key.
+
+    **Richer answer, when the collector binary is reachable:**
+    `daemon status` additionally reports which service supervises the
+    collector and whether a daemon is running. **The binary is not on
+    `PATH`** — nothing puts it there. The plugin's download stub caches it
+    inside the state directory, so invoke it by path, or through the stub:
+
+    ```sh
+    # the stub, which is what every hook uses (works even before the first
+    # download); <plugin> is the installed plugin's root directory
+    sh <plugin>/collector/stub.sh daemon status
+
+    # or the cached binary directly, if one is there already
+    ls ~/.config/sandgarden/bin/     # miranda-collector, or miranda-collector-<version>
+    ~/.config/sandgarden/bin/miranda-collector daemon status
+    ```
+
+    Substitute whichever path `collectorHome()` resolves to (`SANDGARDEN_HOME`
+    → the deprecated `GLORIA_HOME` → `$XDG_CONFIG_HOME/sandgarden` →
+    `~/.config/sandgarden`). `daemon status` always exits 0, so "not
+    enrolled" is not an error. Treat this as extra detail for the report in
+    step 6, not as the enrolment test — the `config.json` check above is the
+    one that has to work on every machine.
+
+### 2. Propose and ask permission — once
+
+Tell the user precisely what will happen, in one message, and ask a single
+yes/no. Cover only the actions actually needed, e.g.:
+
+- create (or replace) `.miranda/USING-MIRANDA.md`;
+- insert the Miranda section into `CLAUDE.md` and `AGENTS.md` (or "replace
+  the existing Miranda section in ...");
+- create `AGENTS.md` containing the section, when neither instruction file
+  exists;
+- enrol this machine for usage tracking, if it is not already, saying what
+  the collector reports (see "What the collector reports").
+
+If everything is already current, say so and skip to step 6. If the user
+declines the file edits, stop — do not partially apply.
+
+### 3. Write the doc
+
+Copy the shipped `USING-MIRANDA.md` to `.miranda/USING-MIRANDA.md`
+**verbatim** (create the `.miranda/` directory if needed). Do not edit,
+reformat, or "improve" the content — refreshes must stay a pure file copy.
+
+### 4. Wire the instruction files
+
+For each of `CLAUDE.md` and `AGENTS.md` that exists at the repo root:
+
+- If it contains a marker block, replace everything from
+  `<!-- miranda:start -->` through `<!-- miranda:end -->` (inclusive) with
+  the section above.
+- Otherwise append the section at the end of the file, preceded by one blank
+  line.
+
+If neither file exists, create `AGENTS.md` containing only the section
+(AGENTS.md is the cross-agent standard; Claude Code reads it too).
+
+### 5. Enable token-usage tracking
+
+Only when step 1 found this machine **unenrolled**.
+
+**Prefer browser enrolment.** Both paths below hand the machine its
+credential without this session ever seeing a secret, which is why they come
+first:
+
+- **Approve the collector's own sign-in prompt.** A daemon running without a
+  credential surfaces a native "Sign in to Miranda" dialog on its first idle
+  start (and at most once a day after that); approving it completes the
+  browser handshake and writes `config.json` itself. Nothing for you to do but
+  tell the user it is waiting for them.
+- **Run the collector's `setup` verb** (by path or through the stub, per step 1
+  — it is not on `PATH`). It prints a miranda.co URL with a short one-time
+  code, opens the browser, and writes the same `config.json` once the user
+  approves the machine while signed in. It also registers the daemon's service
+  if the machine has none.
+
+**Fall back to minting through MCP** — the steps below — for an agent that
+cannot open a browser or drive an interactive terminal, and for a headless
+machine. On a headless machine you can also hand the minted key straight to
+the collector with `setup --token <ingestToken>`, which writes the same
+`config.json` for you rather than you writing it by hand.
+
+**Check before offering one**: `daemon status` (invoked as step 1 describes) is
+how you find out what this build of the collector can do, and a collector
+predating #1227 answers an unrecognised `setup` verb with usage and a non-zero
+exit — go straight to the fallback if so. Whichever path runs, the result is
+the same `config.json` — never do two of them.
+
+#### Fallback: minting the credential through MCP
+
+1. Call the `miranda` MCP tool **`enable_usage_tracking`**, always passing a
+   `machineLabel` — never omit it. Clerk key names must be unique per org,
+   and omitting `machineLabel` falls back to a non-unique default name, so a
+   second machine (or a re-run after a partial failure) collides with an
+   already-minted key and the call fails with a Clerk `409 token_creation_conflict`.
+   Generate a default that's unique per machine, e.g. the hostname plus a
+   short random or timestamp suffix (`<hostname>-<4 random hex chars>`), and
+   use that unless the user asks for a friendlier label — if they supply
+   one, keep it unique the same way (append a short suffix) rather than
+   passing their label bare. It mints a write-only, org-scoped Clerk API key
+   and returns `{ apiBaseUrl, ingestToken }` plus write instructions.
+2. Write `$XDG_CONFIG_HOME/sandgarden/config.json` — `~/.config/sandgarden/config.json`
+   when `XDG_CONFIG_HOME` is unset — directly from the tool result, merging
+   with any existing keys in the file. The directory is per-machine, not
+   per-repo, and shared with the gloria plugin if that's also installed:
+
+   ```json
+   {
+     "ingestToken": "<ingestToken from the tool result>"
+   }
+   ```
+
+   Leave the tool's `apiBaseUrl` out of the file: the collector defaults to
+   `https://gloria.dev`, the only production host. Write it only when it is
+   something else, i.e. a local or dev stack.
+
+   **Never echo the `ingestToken` into the conversation, logs, or any other
+   file** — write it straight to the config file. The secret is shown
+   exactly once; a compromised or lost key is revoked from the Clerk
+   organization settings, and re-running the tool mints a fresh one.
+
+   Work-item cost attribution needs no config beyond this: the collector
+   resolves which gloria/Miranda project a session belongs to itself, per
+   session, from that session's own `git remote` — never from a value in
+   this file, so one machine works correctly across as many
+   gloria-registered repos as the developer has checked out. The collector
+   needs no runtime install: the plugin's first hook fire downloads a
+   compiled, checksum-verified collector binary for this platform (~50 MB,
+   once per collector release) and caches it under `bin/` in that same
+   directory.
+
+   **Manual fallback (MCP not connected on this machine):** any org member
+   can mint the key from a machine that _does_ have the `miranda` MCP server
+   connected (the credential is per-machine, so mint one per machine), or an
+   org admin can create an API key with scope `usage:ingest` for the
+   organization in Clerk and supply it the same way. Have the user write the
+   file themselves — never ask them to paste the secret into the chat.
+
+3. **Verify the write landed — never assume it did.** Read `config.json`
+   back and confirm it parses and carries both keys. A sandboxed agent
+   session can have this write refused: on Codex under Windows the sandbox is
+   process-wide and inherited, and the collector's state directory is outside
+   any workspace root. If the file is absent or unparseable, **do not report
+   tracking as enabled.** Tell the user what to add to
+   `%USERPROFILE%\.codex\config.toml`:
+
+   ```toml
+   [sandbox_workspace_write]
+   writable_roots = ['C:\Users\<you>\.config\sandgarden']
+   ```
+
+   substituting whichever path `collectorHome()` resolves to for them
+   (`SANDGARDEN_HOME` → `GLORIA_HOME` → `%XDG_CONFIG_HOME%\sandgarden` →
+   `C:\Users\<you>\.config\sandgarden`). You cannot apply this edit
+   yourself from a sandboxed session — `~/.codex` is a protected control
+   directory, read-only to the agent even inside a writable root.
+
+   Then say plainly that **the minted credential is gone**: `ingestToken` is
+   shown exactly once, and it was never persisted. After they fix the config,
+   re-run `enable_usage_tracking` with a **fresh, different** `machineLabel` —
+   reusing the previous one collides with the already-minted key and fails
+   with a Clerk `409 token_creation_conflict`.
+
+Collection starts within a minute of that file appearing — the collector
+daemon idles while it is missing and begins the moment it shows up, with no
+restart. The daemon collects **Claude Code, Codex and OpenCode** usage from
+this machine's local session stores whether or not any agent plugin fires, so
+no further wiring is needed. See `USING-MIRANDA.md`'s "Codex, OpenCode, and
+Cursor" section for per-agent notes.
+
+### 6. Report
+
+Summarize what changed (files created/updated, section inserted where,
+usage tracking configured or already present) and suggest committing the
+changes, e.g. `chore: wire miranda agent doc into instruction files`.
+
+## Idempotency rules
+
+- Re-running with identical content is a no-op; say "already current".
+- Marker blocks are always replaced in place, never duplicated. If a file
+  somehow contains multiple marker blocks, replace the first and remove the
+  rest, and mention it.
+- Never touch anything outside the marker block in an instruction file, and
+  never edit any other file.
+- Never re-mint a usage-tracking credential when step 1 found a `config.json`
+  in either location (including the pre-rename `~/.gloria/config.json`). Offer
+  to add `machineLabel` or rotate only if the user asks.
+
+## When to suggest this skill proactively
+
+- The user just installed the Miranda plugin in a repo with no
+  `.miranda/USING-MIRANDA.md` → offer initial setup.
+- The user asks about token cost, usage tracking, or per-issue cost
+  attribution and this machine has no collector `config.json` in either
+  location → offer to set it up.

package/skills/setting-up-usage-tracking/USING-MIRANDA.md

@@ -0,0 +1,298 @@
+# Using Miranda
+
+[Miranda](https://miranda.co) tracks coding-agent token cost and
+attributes it to the GitHub issues the work was actually for. This project
+has adopted Miranda: the triggers below are commitments the team has made,
+not suggestions. When a trigger matches the task you are doing, take the
+corresponding action.
+
+Miranda is available two ways, and both apply to you:
+
+- **MCP tools** on the `miranda` server (`tag_session_work_item`,
+  `enable_usage_tracking`, `get_my_spend`, `get_my_issue_spend`,
+  `get_my_effectiveness`, `get_my_workflow`, `get_my_tracking_status`,
+  `assign_my_session_work_item`, the managers-only `get_team_effectiveness`,
+  plus the shared
+  `get_info`/`register_project`/`put_project_github_info` — the same rows the
+  `gloria` server exposes, since Miranda and gloria share one database).
+- **The usage-collector hooks** installed with the Miranda plugin (Claude
+  Code, Codex, OpenCode) — they run automatically once the collector's
+  `config.json` exists (in `$XDG_CONFIG_HOME/sandgarden`, defaulting to
+  `~/.config/sandgarden`); see "Setting up usage tracking" below.
+
+## Start of every session
+
+One cheap check, done as early as possible — before other work, and
+regardless of what the task turns out to be:
+
+**Declare the work item, and keep it current.** Identify the GitHub issue
+this session is working on and call `tag_session_work_item` with it before
+you start working. Do this silently — do not ask the user to confirm a match
+you are confident in. Work down this list and stop at the first hit:
+
+1. an issue number in the user's request (`#391`, "issue 391", an issue URL);
+2. an issue named earlier in this conversation as the thing being worked on;
+3. an issue number in the current branch name (`feature/foo-123`, `123-foo`,
+   `issue-123`) — the usual case in Conductor-style setups, where each
+   workspace and branch is scoped to one issue;
+4. the issue closed by an open PR for the current branch
+   (`gh pr view --json closingIssuesReferences`) — only worth the round-trip
+   when 1-3 found nothing.
+
+Skip it only when no issue genuinely applies (pure exploration, chores with
+no tracked issue). Never invent a ref just to have one.
+
+**Then declare again whenever the answer could have changed.** This is a
+standing obligation for the whole session, not a one-time step at the start.
+Re-call `tag_session_work_item` when the branch is renamed, when the user
+names a different issue, when a PR is opened against a different issue, or
+when you discover mid-session that the real work item is another one. Your
+declaration outranks every signal collected automatically, so it is the
+**only** thing that can correct a session already credited to the wrong
+issue — a stale declaration is not neutral, it silently keeps the session's
+entire cost on the wrong issue. The call is session-local (transcript only,
+no database round-trip), so calling it again costs nothing, and the most
+recent call always wins.
+
+## When cost comes up
+
+The other standing trigger, and the one most sessions will never fire. When
+the user asks what something cost — their own spend, this issue's cost,
+whether the work is getting cheaper — answer from the tools rather than
+estimating, and pick by the question:
+
+- **"What have I been spending?"** → `get_my_spend`. One window (`range`:
+  `7d`, `30d`, `90d` or `month`, `30d` by default), with the prior period and
+  its delta and ranked breakdowns by project, AI tool and model.
+- **"What has this issue cost?"** → `get_my_issue_spend`, with `projectSlug`
+  and the same issue you declared as `workItemRef`. That answer is the
+  issue's **lifetime** cost, not a window's, set against the median of your
+  own closed issues of the same type. Omit `workItemRef` to rank your
+  costliest issues in that project for the range instead.
+- **"Is my work getting cheaper, or better attributed?"** →
+  `get_my_effectiveness` (`30d` or `90d`): cost per closed issue and median
+  cycle time per GitHub issue type, how much of your spend reached an issue
+  at all, spend per coding agent, how much of the spend still booked to a
+  pull request actually merged, and — when the org has turned workflow
+  collection on — your own workflow medians and practice adoption per type.
+- **"How do I work with agents, compared with my team?"** →
+  `get_my_workflow` (`30d` or `90d`): per GitHub issue type, your settled
+  sessions' medians (human prompts, autonomy, interrupts, active time, tool
+  calls and errors) and how often each practice held, against the team's band
+  for the same type. It names nobody: no band below 3 other developers, and
+  "not enough closed work" below 5 of your closed items. If the org has not
+  turned workflow collection on, it says so and returns no figures — an org
+  admin with `settings:manage` can turn it on in Settings.
+- **"How is my team doing, per kind of work?"** (managers only) →
+  `get_team_effectiveness` (`30d` or `90d`): the same scoreboard as Miranda's
+  Effectiveness page, naming each developer — per issue type, closed work,
+  cost per closed, cycle time, prompts and sessions per closed, attributed
+  share and practices adopted, each banded against the team median (never a
+  decimal ratio), "not enough closed work" below 5 closed items, and greyed
+  below 60% attributed share. It needs `settings:manage`; anyone else gets
+  "You do not have access." Off for the org, it says collection is not
+  enabled. For coaching and tooling choices, not a performance rating.
+- **"Is any of this even being recorded?"** → `get_my_tracking_status`: every
+  machine you own and whether its collector is live, stale or silent, plus
+  your recent sessions with no confirmed work item.
+
+Every one of these but `get_team_effectiveness` answers about **you**, the
+authenticated caller. None takes a user argument and none reports the org's
+numbers or anyone else's — the one team figure, `get_my_workflow`'s band, is
+an aggregate that never names or counts anyone — so they are safe to call
+without asking permission. `get_team_effectiveness` is the exception: it
+names developers, so it answers only a caller with `settings:manage`; relay
+it to the manager who asked, not to the team. Any other team or project-wide
+view is the Miranda dashboard's job, not an MCP tool's — point the user there
+instead of trying to assemble one.
+
+**Repair attribution before quoting any of it.** `get_my_tracking_status`
+lists your unattributed and ambiguous sessions, each naming the `projectSlug`
+it needs; call `assign_my_session_work_item` (`projectSlug`, `sessionId`,
+`workItemRef`) on each one, then re-read. You are the only person who can —
+it refuses anyone else's session, an admin's included — and every per-issue
+figure above is only as good as the attribution behind it. A session that has
+already resolved to an issue is reported back as skipped, never overwritten.
+
+**None of them tells you what THIS session has cost so far.** They read what
+the collector has already reported, and the session you are in is still in
+flight. The collector's `gloria-usage session` subcommand will answer that
+locally, with no round-trip, once it ships; until then, say the current
+session's cost isn't available yet rather than estimating it.
+
+## Setting up usage tracking
+
+The Miranda plugin ships hooks (Claude Code, Codex, OpenCode) that transmit
+**token usage only** (model names, token counts, timestamps, session ids, a
+locally-minted random machine UUID, and this machine's hostname, OS and
+architecture so machines are distinguishable in the dashboard — never message
+content, prompts, or code). Cursor's hooks are wired too but are currently a no-op — see the
+Cursor note below. They are inert until that `config.json` exists, so offer
+to set it up if it doesn't — the `setting-up-usage-tracking` skill drives
+this end to end.
+
+## MCP tools reference
+
+All tools run as the authenticated user against their active organization.
+Reads need `inventory:read` (any member); writes need `inventory:write`.
+
+- `get_info` — org id/name/slug. Cheap; call it first when you need org
+  context or to check the `miranda` MCP server is reachable.
+- `register_project`, `put_project_github_info` — register this repo as a
+  gloria.dev/Miranda project (the same rows either server writes).
+- `tag_session_work_item` — declare the GitHub issue this session is working
+  on (bare issue number, `gh:482`, or a full issue URL). Session-local — it
+  writes only to this session's own transcript, never the database — the
+  local usage collector reads it back out and reports it for per-issue token
+  cost attribution. Call it as soon as the issue is known, and **again**
+  every time the work item changes; the most recent declaration wins and
+  outranks every automatically-collected signal. See "Start of every
+  session".
+- `enable_usage_tracking` — mint a write-only, org-scoped Clerk API key and
+  return it as the `ingestToken` for this machine's collector. The collector
+  needs no base URL; it defaults to `https://gloria.dev`. See
+  "Setting up usage tracking".
+- `get_my_spend` — your own spend for a window (`range`:
+  `7d`/`30d`/`90d`/`month`, default `30d`): actual spend with its
+  plans-vs-tokens split, the prior period and its delta, how many days you
+  ran an agent and your average on those days, your heaviest day, and ranked
+  breakdowns by project, AI tool and model. Takes no user argument.
+- `get_my_issue_spend` — one issue's lifetime cost, your own share of it, how
+  many sessions were booked to it, and GitHub's own state, type and
+  timestamps, against the median cost of your own closed issues of that type.
+  Requires `projectSlug`. Pass `workItemRef` for a single issue — `range` is
+  ignored, because an issue's cost is the whole of its life — or omit it to
+  rank your costliest issues in that project for the range.
+- `get_my_effectiveness` — your own effectiveness for `30d` or `90d`,
+  org-wide across every project: per GitHub issue type, issues closed and
+  still open, cost per closed issue and median cycle time; your attribution
+  split (unattributed, ambiguous, or still booked to a pull request rather
+  than an issue); spend, share and requests per coding agent; of the
+  pull-request-booked spend, what merged versus closed unmerged, the cost per
+  merged pull request, and review comments per merged pull request; and a
+  `workflow` section — your own settled sessions' profile medians and
+  practice adoption per issue type, as `get_my_workflow` reports them but
+  without the team band. `workflow` is null, with a not-enabled message, when
+  the org has not turned workflow collection on; every other figure still
+  works. One window governs every figure, so it is a within-period rate — use
+  `get_my_issue_spend` for an issue's lifetime cost.
+- `get_my_workflow` — your own workflow for `30d` or `90d`, per GitHub issue
+  type: the medians of your settled sessions' profile (human prompts, tokens
+  per prompt, assistant turns per prompt, interrupts, active seconds, tool
+  calls, tool error rate) and your practice adoption, each against the team
+  band (p25, median, p75) for the same type, with a ready sentence per
+  figure. Below 5 of your closed items a type shows "not enough closed work";
+  below 3 other developers the band is omitted. Off for the org, it returns
+  only a not-enabled message.
+- `get_team_effectiveness` — managers only (`settings:manage`): the org's
+  effectiveness scoreboard for `30d` or `90d`, the same rows, gates, bands and
+  greying as Miranda's Effectiveness page. Per developer (named) × GitHub
+  issue type: closed items and merged pull requests, cost per closed, median
+  cycle time, human prompts, sessions and active hours per closed, review
+  comments per merged pull request, merged and attributed share, and the
+  practices adopted, each per-unit figure banded (well below, below,
+  around, above, well above) against the team median beside the team row it
+  was drawn from. Below 5
+  closed items a row shows "not enough closed work"; under 60% attributed
+  share it is greyed with the reason. Off for the org, it returns only a
+  not-enabled message.
+- `get_my_tracking_status` — takes no arguments. Your machines with what each
+  has cost and whether its collector is live, stale or has never sent a
+  heartbeat, plus your recent sessions with no confirmed work item — their
+  cost, branch, working directory, start time, and the `projectSlug` needed
+  to repair each one.
+- `assign_my_session_work_item` — attach one of your own past sessions to a
+  GitHub issue: `projectSlug`, `sessionId` (as `get_my_tracking_status`
+  reports it) and `workItemRef` (the same three forms
+  `tag_session_work_item` accepts). Self-service only — anyone else's session
+  is refused, an admin's included.
+
+## First-time and recovery
+
+- **No work item applies to this session** — skip `tag_session_work_item`;
+  its cost simply won't attribute to an issue. Don't guess a ref just to have
+  one. If one becomes clear later, declare it then — a late declaration
+  still attributes the session's whole cost, including what was already
+  spent.
+- **You declared the wrong issue** — call `tag_session_work_item` again with
+  the right one. The later declaration supersedes the earlier one and moves
+  the already-credited cost with it. There is no way to clear a declaration
+  other than replacing it, and no lower-ranked signal (a branch rename, a
+  PR's `Closes #N`) can override one — so correcting it is on you.
+- **MCP auth fails** — the user must log in to the `miranda` server: Claude
+  Code `/mcp` → miranda → authenticate; Codex `codex mcp login miranda`;
+  OpenCode follows its MCP auth flow. Until then, `tag_session_work_item`
+  and the other tools above are unavailable — mention it and continue
+  without them.
+- **This file is missing or contradicts the tools you see** — trust the live
+  MCP server, and offer to re-run `setting-up-usage-tracking`.
+
+## Codex, OpenCode, and Cursor
+
+**Codex:** the Codex plugin manifest (`.codex-plugin/plugin.json`) declares
+the same `Stop`/`SessionStart` hooks Claude Code uses, pointing at the same
+collector. Codex's own hooks documentation describes `Stop` as a genuine
+turn-level event, distinct from `SessionStart`, with a payload shape
+(`session_id`/`transcript_path`/`cwd`) that matches Claude Code's — so once
+that plugin path fires, `hook-stop` handles it correctly: it names the
+rollout file in the trigger it writes, and the daemon detects a Codex rollout
+by name and parses it with the Codex parser instead of Claude Code's. This is
+still not empirically confirmed against a live Codex install, so treat it as
+expected-but-unverified rather than a guarantee.
+
+**Windows — required, or nothing is recorded.** Codex's sandbox is selected
+process-wide on Windows (`windows.sandbox`) and child processes inherit it,
+unlike macOS/Linux where Codex sandboxes each command individually. Hook
+commands therefore inherit the restriction, and the collector's state
+directory sits outside any workspace root — so its writes are blocked, and so
+is this skill's own `config.json` write. The failure is silent: hook
+subcommands never exit non-zero by design. The user must add that directory
+as a writable root in `%USERPROFILE%\.codex\config.toml` **before** setup
+runs:
+
+```toml
+[sandbox_workspace_write]
+writable_roots = ['C:\Users\<you>\.config\sandgarden']
+```
+
+TOML single quotes are literal strings, so backslashes stay as typed; double
+quotes would need each one escaped. `C:\Users\<you>\.config\sandgarden` is
+the default — substitute `SANDGARDEN_HOME`, the deprecated `GLORIA_HOME`, or
+`%XDG_CONFIG_HOME%\sandgarden` if any is set, in that precedence order. You
+cannot make this edit on the user's behalf from inside a sandboxed session:
+`~/.codex` is a protected control directory, read-only to the agent even when
+its parent is a writable root.
+
+As a manual fallback (or on a Codex-only machine that hasn't installed the
+plugin), point `notify` in `~/.codex/config.toml` at the collector download
+stub directly:
+
+```toml
+notify = ["sh", "/path/to/plugins/miranda/collector/stub.sh", "hook-notify"]
+```
+
+`notify` fires on every turn completion and carries a `thread-id` +
+`cwd` JSON payload. `hook-notify` resolves the one rollout file for that
+`thread-id` and tells the collector daemon to ingest it now — the same
+lightweight, single-file trigger `hook-stop` gives Claude Code. A malformed
+payload, or a `thread-id` with no matching rollout file yet (e.g. the very
+first turn of a brand new session), simply triggers nothing: the daemon
+watches Codex's rollout directories itself, so that turn is still collected
+seconds later. Pointing `notify` at `hook-session-start` instead also works
+— it just makes sure a daemon is running without naming a file.
+
+**OpenCode:** the Miranda OpenCode plugin (`.opencode/plugins/miranda.js`)
+wires `session.created` and `session.idle` to make sure this machine's
+collector daemon is running — this ships automatically with the plugin, no
+manual step needed. OpenCode keeps its sessions in SQLite rather than in a
+transcript file, so there is nothing per-session to name; the daemon watches
+OpenCode's storage directory and collects from it directly.
+
+**Cursor:** the Cursor plugin wires `stop`/`sessionStart`/`sessionEnd` hooks
+too, but they call the collector's `hook-cursor` entrypoint, which is a
+**deliberate no-op**. Cursor hook payloads carry no token usage or cost data,
+and Cursor's own local session storage is unreliable for it (missing cache
+tokens, mostly-zeroed counts on current versions) — the accurate source is
+the Team/Enterprise Admin API, which has no collector adapter yet. Be honest
+about this status: Cursor sessions do not contribute usage data today, even
+though the hooks are wired.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.