ashlr-plugin 1.36.4 → 1.37.1

package/scripts/_read-thresholds.ts

@@ -0,0 +1,119 @@
+/**
+ * scripts/_read-thresholds.ts
+ *
+ * Report-only threshold recommendations for scripts/bench-read-real.ts.
+ * Pure functions: no I/O, no defaults changed anywhere. The bench prints the
+ * result next to the current defaults so a human can decide.
+ *
+ * Derivation (break-even by size bin):
+ *   1. Put each file in a fixed-width byte bin (default 256 bytes).
+ *   2. Ignore bins with fewer than `minFiles` files (default 3) as too sparse.
+ *   3. A bin "wins" when its aggregate candidate tokens are no more than its
+ *      aggregate baseline tokens.
+ *   4. The recommendation is the lower edge of the earliest qualified bin from
+ *      which every qualified bin upward wins. If the largest qualified bin
+ *      loses, there is no recommendation.
+ *   5. If the very first qualified bin already wins, the data cannot see the
+ *      true break-even, so the result is marked as bounded by the smallest
+ *      sampled size ("at or below").
+ */
+
+export interface ReadSample {
+  /** File size in bytes. */
+  bytes: number;
+  /** Baseline tokens (raw file, or the snip view for the AST comparison). */
+  baseline: number;
+  /** Candidate tokens (ashlr__read output, or the AST view). */
+  candidate: number;
+}
+
+export interface BinStat {
+  /** Inclusive lower edge in bytes. */
+  from: number;
+  files: number;
+  baseline: number;
+  candidate: number;
+  wins: boolean;
+}
+
+export interface BreakEven {
+  /** Recommended threshold in bytes, or null when no size range reliably wins. */
+  bytes: number | null;
+  /** True when the first qualified bin already wins (true break-even may be lower). */
+  atOrBelow: boolean;
+  samples: number;
+  qualifiedBins: number;
+  bins: BinStat[];
+}
+
+export interface BreakEvenOptions {
+  binBytes?: number;
+  minFiles?: number;
+}
+
+export function deriveBreakEven(samples: ReadSample[], opts: BreakEvenOptions = {}): BreakEven {
+  const binBytes = opts.binBytes ?? 256;
+  const minFiles = opts.minFiles ?? 3;
+  const byBin = new Map<number, BinStat>();
+  for (const s of samples) {
+    if (!Number.isFinite(s.bytes) || s.bytes < 0) continue;
+    const from = Math.floor(s.bytes / binBytes) * binBytes;
+    const bin = byBin.get(from) ?? { from, files: 0, baseline: 0, candidate: 0, wins: false };
+    bin.files++;
+    bin.baseline += s.baseline;
+    bin.candidate += s.candidate;
+    byBin.set(from, bin);
+  }
+  const bins = [...byBin.values()].sort((a, b) => a.from - b.from);
+  for (const b of bins) b.wins = b.candidate <= b.baseline;
+  const qualified = bins.filter((b) => b.files >= minFiles);
+  let start = qualified.length;
+  while (start > 0 && qualified[start - 1]!.wins) start--;
+  const found = start < qualified.length;
+  return {
+    bytes: found ? qualified[start]!.from : null,
+    atOrBelow: found && start === 0,
+    samples: samples.length,
+    qualifiedBins: qualified.length,
+    bins,
+  };
+}
+
+export interface ThresholdReport {
+  name: string;
+  current: number;
+  derivation: string;
+  result: BreakEven;
+}
+
+function describe(r: BreakEven): string {
+  if (r.bytes === null) return "none (no size range where every bin breaks even)";
+  return r.atOrBelow ? `<= ${r.bytes} B (wins from the smallest sampled bin)` : `${r.bytes} B`;
+}
+
+/** Lines the bench prints. Always states that defaults are unchanged. */
+export function formatThresholdReport(
+  reports: ThresholdReport[],
+  ctx: { every: number; binBytes: number; minFiles: number },
+): string[] {
+  const out: string[] = [];
+  out.push("");
+  out.push("Recommended read thresholds (report only, no default is changed)");
+  for (const r of reports) {
+    out.push(
+      `  ${r.name.padEnd(22)} current ${String(r.current).padStart(5)} B   recommended ${describe(r.result)}`,
+    );
+    out.push(
+      `    from ${r.result.samples} files, ${r.result.qualifiedBins} bins with >= ${ctx.minFiles} files; ${r.derivation}`,
+    );
+  }
+  out.push(
+    `  How: ${ctx.binBytes} B size bins; the threshold is the lower edge of the first bin from which every bin`,
+  );
+  out.push("  with enough files has candidate tokens <= baseline tokens.");
+  out.push(
+    `  Caveat: derived from this repo's own tracked files (every Nth file, N=${ctx.every}) with estimated tokens,`,
+  );
+  out.push("  not a real tokenizer. Synthetic; other codebases will differ. Review before changing any default.");
+  return out;
+}

package/scripts/ashlr-mcp.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * ashlr-mcp package bin — node launcher for the stdio MCP router.
+ *
+ * npm installs this as `ashlr-mcp`. It runs under node so a missing bun gets
+ * the same first-run handling as the plugin manifests (scripts/bootstrap.mjs:
+ * find ~/.bun/bin, else install bun unless ASHLR_NO_AUTO_INSTALL=1) instead of
+ * `/usr/bin/env: 'bun': No such file or directory`. scripts/ashlr-mcp.ts stays
+ * the source-checkout entry (`bun run scripts/ashlr-mcp.ts`).
+ */
+
+process.env.ASHLR_MCP_HOST ||= "generic";
+process.argv.splice(2, 0, "servers/_router.ts");
+
+await import("./bootstrap.mjs");

package/scripts/ashlr-mcp.ts

@@ -15,6 +15,9 @@ const __filename = fileURLToPath(import.meta.url);
 const PLUGIN_ROOT = resolve(dirname(__filename), "..");
 
 process.env.ASHLR_MCP_HOST ||= "generic";
+// The router runs from PLUGIN_ROOT; keep the launch folder (the user's project)
+// so the cwd clamp allows it.
+process.env.ASHLR_LAUNCH_CWD ||= process.cwd();
 
 const entrypoint = join(PLUGIN_ROOT, "scripts", "mcp-entrypoint.ts");
 const child = Bun.spawn(

package/scripts/ashlr-plugin.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * ashlr-plugin package bin — node launcher for scripts/cli.ts.
+ *
+ * npm installs this as `ashlr-plugin`. The CLI itself runs under bun; this
+ * shim finds bun (PATH, then ~/.bun/bin) and otherwise explains how to get it,
+ * instead of failing with `/usr/bin/env: 'bun': No such file or directory`.
+ * It never installs anything.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hasBun, prependBunToPath } from "./bun-resolve.mjs";
+import { buildHandshake, wantsHandshake } from "./handshake.mjs";
+
+if (!hasBun()) prependBunToPath();
+
+// Companion handshake (docs/ashlr-handshake.md): answered here, before the
+// bun check, so a machine without bun still gets an answer saying so.
+if (wantsHandshake(process.argv.slice(2))) {
+  const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const { version } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const phantom = spawnSync("phantom", ["--version"], { stdio: "ignore" }).status === 0;
+  process.stdout.write(`${JSON.stringify(buildHandshake(version, { bun: hasBun(), phantom }))}\n`);
+  process.exit(0);
+}
+if (!hasBun()) {
+  process.stderr.write(
+    "ashlr-plugin needs Bun 1.3 or newer, and bun was not found on PATH or in ~/.bun/bin.\n" +
+      "Install it: curl -fsSL https://bun.sh/install | bash   (Windows: irm bun.sh/install.ps1 | iex)\n" +
+      "Then open a new terminal and run ashlr-plugin again.\n",
+  );
+  process.exit(1);
+}
+
+const cli = join(dirname(fileURLToPath(import.meta.url)), "cli.ts");
+const child = spawn("bun", ["run", cli, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    try {
+      child.kill(signal);
+    } catch {
+      // Child may already be gone.
+    }
+  });
+}
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Our own SIGINT/SIGTERM listeners above replace node's default action,
+    // so re-raising with them attached would just exit 0. Drop them first so
+    // the signal terminates this process the way it terminated the child.
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+  } else process.exit(code ?? 0);
+});

package/scripts/bench-read-real.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env bun
+/**
+ * scripts/bench-read-real.ts
+ *
+ * Measures the real ashlrRead handler (line numbering, snip, badge included)
+ * against raw file tokens, bucketed by file size. run-benchmark.ts mirrors only
+ * snipCompact, so it cannot see per-line overhead on small files.
+ *
+ *   bun run scripts/bench-read-real.ts [--every N]   # every Nth tracked text file (default 3)
+ *
+ * Synthetic: token counts come from estimateTokensFromString, not a real tokenizer.
+ * Same-commit comparison: run it before and after a change on the same file list.
+ *
+ * It also prints report-only recommended thresholds (see _read-thresholds.ts):
+ *   - read redirect: where ashlr__read output stops being larger than the raw file
+ *   - AST skeleton: where the AST view beats the snip view for TS/JS files
+ * No default is changed. Pass --no-thresholds to skip the extra AST reads.
+ */
+import { readFileSync } from "fs";
+import { execSync } from "child_process";
+import { resolve } from "path";
+import { AST_THRESHOLD, ashlrRead } from "../servers/read-server.ts";
+import { invalidateCached } from "../servers/_read-cache.ts";
+import { NUDGE_READ_THRESHOLD } from "../hooks/pretooluse-common.ts";
+import { deriveBreakEven, formatThresholdReport, type ReadSample } from "./_read-thresholds.ts";
+import { estimateTokensFromString } from "@ashlr/core-efficiency";
+
+const every = Number(process.argv[process.argv.indexOf("--every") + 1]) || 3;
+const files = execSync(
+  "git ls-files -- '*.ts' '*.md' '*.json' '*.sh' '*.tsx' | grep -v -E 'bun.lock|^bench/refs|^video|^site|^scripts/bench-read-real'",
+  { encoding: "utf-8", maxBuffer: 1e8 },
+).trim().split("\n");
+const bucket = (n: number) => n < 1000 ? "a <1K" : n < 1700 ? "b 1-1.7K" : n < 2500 ? "c 1.7-2.5K" : n < 5000 ? "d 2.5-5K" : n < 15000 ? "e 5-15K" : "f 15K+";
+const b: Record<string, { n: number; r: number; a: number; worse: number }> = {};
+const thresholds = !process.argv.includes("--no-thresholds");
+const readSamples: ReadSample[] = [];
+const astSamples: ReadSample[] = [];
+const astLangs = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+let tr = 0, ta = 0, k = 0;
+for (const f of files) {
+  let raw: string;
+  try { raw = readFileSync(f, "utf-8"); } catch { continue; }
+  if (!raw.length || raw.length > 400000) continue;
+  if (k++ % every) continue;
+  let out: string;
+  try { out = await ashlrRead({ path: f }); } catch { continue; }
+  const r = estimateTokensFromString(raw), a = estimateTokensFromString(out);
+  tr += r; ta += a;
+  const x = (b[bucket(raw.length)] ??= { n: 0, r: 0, a: 0, worse: 0 });
+  x.n++; x.r += r; x.a += a; if (a > r) x.worse++;
+  readSamples.push({ bytes: raw.length, baseline: r, candidate: a });
+  if (thresholds && astLangs.test(f)) {
+    // Compare the two views directly; drop the cache entry between reads.
+    const abs = resolve(f);
+    try {
+      invalidateCached(abs);
+      const snip = await ashlrRead({ path: f, mode: "snip" });
+      invalidateCached(abs);
+      const ast = await ashlrRead({ path: f, mode: "ast" });
+      invalidateCached(abs);
+      astSamples.push({ bytes: raw.length, baseline: estimateTokensFromString(snip), candidate: estimateTokensFromString(ast) });
+    } catch { /* skip files either view cannot read */ }
+  }
+}
+for (const key of Object.keys(b).sort()) {
+  const v = b[key]!;
+  console.log(key.slice(2).padEnd(10), "files", String(v.n).padStart(4), "raw", String(v.r).padStart(7), "ashlr", String(v.a).padStart(7), ((v.a / v.r - 1) * 100).toFixed(1).padStart(6) + "%", "worse-than-raw", v.worse);
+}
+console.log("TOTAL".padEnd(10), "raw", tr, "ashlr", ta, ((ta / tr - 1) * 100).toFixed(1) + "%");
+if (thresholds) {
+  const binBytes = 256, minFiles = 3;
+  const lines = formatThresholdReport(
+    [
+      {
+        name: "read redirect",
+        current: NUDGE_READ_THRESHOLD,
+        derivation: "candidate = ashlr__read output, baseline = raw file",
+        result: deriveBreakEven(readSamples, { binBytes, minFiles }),
+      },
+      {
+        name: "AST skeleton (TS/JS)",
+        current: AST_THRESHOLD,
+        derivation: "candidate = AST view, baseline = snip view",
+        result: deriveBreakEven(astSamples, { binBytes, minFiles }),
+      },
+    ],
+    { every, binBytes, minFiles },
+  );
+  for (const l of lines) console.log(l);
+}

package/scripts/bootstrap.mjs

@@ -49,12 +49,14 @@ function autoInstallBun() {
           "-Command",
           "irm bun.sh/install.ps1 | iex",
         ],
-        { stdio: ["ignore", "inherit", "inherit"] },
+        // The installer's stdout goes to stderr: our stdout is the MCP
+        // channel, and an installer banner there corrupts the first frame.
+        { stdio: ["ignore", 2, "inherit"] },
       )
     : spawnSync(
         "bash",
         ["-lc", "curl -fsSL https://bun.sh/install | bash"],
-        { stdio: ["ignore", "inherit", "inherit"] },
+        { stdio: ["ignore", 2, "inherit"] },
       );
   if (result.status !== 0) {
     log("bun installer failed. Install manually: https://bun.sh/docs/installation");
@@ -78,6 +80,9 @@ if (!hasBun()) {
 }
 
 const entrypoint = join(PLUGIN_ROOT, "scripts", "mcp-entrypoint.ts");
+// The router runs from PLUGIN_ROOT, so record the folder the host launched us
+// in first: that is the user's project, and the cwd clamp allows it.
+process.env.ASHLR_LAUNCH_CWD ||= process.cwd();
 const child = spawn("bun", ["run", entrypoint, ...process.argv.slice(2)], {
   cwd: PLUGIN_ROOT,
   stdio: ["inherit", "inherit", "inherit"],
@@ -95,6 +100,11 @@ for (const signal of ["SIGINT", "SIGTERM"]) {
 }
 
 child.on("exit", (code, signal) => {
-  if (signal) process.kill(process.pid, signal);
-  else process.exit(code ?? 0);
+  if (signal) {
+    // Our own SIGINT/SIGTERM listeners above replace node's default action,
+    // so re-raising with them attached would just exit 0. Drop them first so
+    // the signal terminates this process the way it terminated the child.
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+  } else process.exit(code ?? 0);
 });

package/scripts/cli.ts

@@ -10,7 +10,7 @@
  *   ashlr-plugin tools [--json]                    # list registered MCP tools
  *   ashlr-plugin version                          # print ashlr-plugin version
  *   ashlr-plugin mcp                              # start the stdio MCP router
- *   ashlr-plugin codex-doctor --json              # Codex plugin packaging health
+ *   ashlr-plugin codex-doctor --json              # Codex plugin packaging health (alias: doctor)
  *   ashlr-plugin codex-install --dry-run --json   # planned Codex config changes
  *
  * Output is stable JSON on stdout. Errors go to stderr with a human-readable
@@ -24,21 +24,29 @@ import { fileURLToPath } from "url";
 
 const STATS_PATH = join(homedir(), ".ashlr", "stats.json");
 
-function usage(): never {
+function usage(exitCode = 1): never {
   process.stderr.write(
     `usage:\n` +
     `  ashlr-plugin stats --json [--session <id>] [--since <YYYY-MM-DD>] [--tool <name>]\n` +
+    `      print the local savings ledger (or one slice of it) as JSON\n` +
     `  ashlr-plugin tools [--json]\n` +
+    `      list the MCP tools the router registers\n` +
     `  ashlr-plugin mcp\n` +
+    `      start the stdio MCP router\n` +
     `  ashlr-plugin codex-start [--json]\n` +
     `  ashlr-plugin codex-resume [--json]\n` +
     `  ashlr-plugin codex-end [--json]\n` +
+    `      Codex session lifecycle hooks\n` +
     `  ashlr-plugin codex-doctor [--json]\n` +
+    `      check the plugin's install and Codex packaging (alias: doctor)\n` +
     `  ashlr-plugin codex-install --dry-run [--json]\n` +
+    `      show the Codex config changes an install would make\n` +
     `  ashlr-plugin genome-refresh [--json]\n` +
-    `  ashlr-plugin version\n`,
+    `      refresh genome sections for changed files\n` +
+    `  ashlr-plugin version\n` +
+    `      print the plugin version\n`,
   );
-  process.exit(1);
+  process.exit(exitCode);
 }
 
 function repoRootFromCli(): string {
@@ -48,8 +56,13 @@ function repoRootFromCli(): string {
 
 function loadStats(): Record<string, unknown> {
   if (!existsSync(STATS_PATH)) {
-    process.stderr.write(`ashlr-plugin: no stats yet at ${STATS_PATH}\n`);
-    process.exit(1);
+    // No savings recorded yet: answer with an empty ledger so `--json`
+    // callers always get JSON.
+    return {
+      schemaVersion: 2,
+      sessions: {},
+      lifetime: { calls: 0, tokensSaved: 0, rawTotal: 0, byTool: {}, byDay: {} },
+    };
   }
   try {
     return JSON.parse(readFileSync(STATS_PATH, "utf-8"));
@@ -144,8 +157,10 @@ function runStats(flags: Record<string, string | boolean>): void {
       process.stderr.write(`ashlr-plugin: --since must be YYYY-MM-DD (got ${since})\n`);
       process.exit(1);
     }
-    const lifetime = (stats.lifetime ?? {}) as { daily?: Record<string, unknown> };
-    const daily = lifetime.daily ?? {};
+    // The ledger keeps per-day totals in lifetime.byDay (older builds of this
+    // command read a `daily` key that the ledger never had).
+    const lifetime = (stats.lifetime ?? {}) as { byDay?: Record<string, unknown> };
+    const daily = lifetime.byDay ?? {};
     const filtered: Record<string, unknown> = {};
     for (const [date, entry] of Object.entries(daily)) {
       if (date >= since) filtered[date] = entry;
@@ -163,6 +178,9 @@ function runVersion(): void {
 async function runMcp(): Promise<void> {
   const root = repoRootFromCli();
   process.env.ASHLR_MCP_HOST ||= "generic";
+  // The router runs from the plugin root; keep the caller's folder (the
+  // user's project) so the router can move back into it.
+  process.env.ASHLR_LAUNCH_CWD ||= process.cwd();
   const proc = Bun.spawn(
     ["bun", "run", join(root, "scripts", "mcp-entrypoint.ts"), "servers/_router.ts"],
     {
@@ -233,7 +251,7 @@ function runCodexDoctor(flags: JsonFlagMap): void {
   const server = mcp?.mcpServers?.ashlr;
   const instructions = typeof server?.instructions === "string" ? server.instructions : "";
   const allowlist = process.env.ASHLR_ALLOW_PROJECT_PATHS ?? "";
-  const mcpBinDeclared = pkg?.bin?.["ashlr-mcp"] === "./scripts/ashlr-mcp.ts";
+  const mcpBinDeclared = pkg?.bin?.["ashlr-mcp"] === "./scripts/ashlr-mcp.mjs";
   const mcpBinResolvable = commandOnPath("ashlr-mcp");
   const sourceCheckoutCommand = `bun run ${join(root, "scripts", "ashlr-mcp.ts")}`;
   const mcpHealthy = Boolean(
@@ -358,6 +376,12 @@ function runCodexDoctor(flags: JsonFlagMap): void {
     `ashlr Codex doctor: ${report.ok ? "ok" : "issues found"}\n` +
       `- plugin manifest: ${report.pluginManifest.present ? "present" : "missing"}\n` +
       `- MCP server: ${report.mcp.server ? "present" : "missing"} (${report.mcp.bin})\n` +
+      // Report-only: `ok` does not depend on this. The plugin's .mcp.json runs
+      // `ashlr-mcp`, so a host cannot start the server when it is not on PATH.
+      (report.mcp.binResolvable
+        ? "- MCP launch: ashlr-mcp is on PATH\n"
+        : "- MCP launch: ashlr-mcp is not on PATH, so a host that runs .mcp.json cannot start the server. " +
+          `Install the package bin (npm install -g ashlr-plugin) or point the host at: ${report.mcp.sourceCheckoutCommand}\n`) +
       `- hooks: ${report.hooks.present ? "present" : "missing"} (${report.hooks.defaultMode})\n` +
       `- skills: ${report.skills.present ? "present" : "missing"}\n` +
       `- agents: ${report.agents.present ? "present" : "missing"}\n`,
@@ -451,6 +475,7 @@ async function main(): Promise<void> {
       runCodexLifecycle(subcommand, flags);
       break;
     case "codex-doctor":
+    case "doctor":
       runCodexDoctor(flags);
       break;
     case "codex-install":
@@ -467,7 +492,7 @@ async function main(): Promise<void> {
     case "--help":
     case "-h":
     case "help":
-      usage();
+      usage(0);
       break;
     default:
       process.stderr.write(`ashlr-plugin: unknown subcommand "${subcommand}"\n`);

package/scripts/context-status.ts

@@ -17,7 +17,8 @@
  */
 
 import { openContextDb } from "../servers/_embedding-cache";
-import { EMBED_DIM } from "../servers/_embedding-model";
+import { EMBED_DIM, embedFormat } from "../servers/_embedding-model";
+import { safeTargetLabel } from "../servers/_gateway-target.ts";
 
 if (process.env.ASHLR_CONTEXT_DB_DISABLE === "1") {
   console.log("ashlr context-db: disabled (ASHLR_CONTEXT_DB_DISABLE=1)");
@@ -31,8 +32,12 @@ db.close();
 const mbSize = (s.dbBytes / (1024 * 1024)).toFixed(2);
 const hitPct = (s.hitRateLast1000 * 100).toFixed(1);
 
+// The OpenAI-compatible mode may point at a Phantom proxy URL carrying a
+// session token, so it is shown as scheme://host:port only.
 const embedderLine = process.env.ASHLR_EMBED_URL
-  ? `bm25 (dim=${EMBED_DIM}) + remote: ${process.env.ASHLR_EMBED_URL}`
+  ? embedFormat() === "openai"
+    ? `bm25 (dim=${EMBED_DIM}) + remote (openai format): ${safeTargetLabel(process.env.ASHLR_EMBED_URL)}`
+    : `bm25 (dim=${EMBED_DIM}) + remote: ${process.env.ASHLR_EMBED_URL}`
   : `bm25 (dim=${EMBED_DIM})`;
 
 console.log(`ashlr context-db`);

package/scripts/deploy-smoke.sh

@@ -33,6 +33,12 @@ pass() { echo -e "${GRN}PASS${RST}  $1"; PASS=$((PASS + 1)); }
 fail() { echo -e "${RED}FAIL${RST}  $1"; FAIL=$((FAIL + 1)); }
 info() { echo -e "${YLW}----${RST}  $1"; }
 
+# curl with the bearer header read from a config on stdin, so the token is
+# never a curl argument (argv is visible to other local users in `ps`).
+auth_curl() {
+  printf 'header = "Authorization: Bearer %s"\n' "$TOKEN" | curl --config - "$@"
+}
+
 # ---------------------------------------------------------------------------
 # 1. Site health
 # ---------------------------------------------------------------------------
@@ -83,9 +89,8 @@ if [ -z "$TOKEN" ]; then
   info "ASHLR_TOKEN not set — skipping authenticated badge + stats checks"
 else
   # Upload a minimal stats payload to create a user record
-  SYNC_STATUS=$(curl -sf -o /dev/null -w "%{http_code}" \
+  SYNC_STATUS=$(auth_curl -sf -o /dev/null -w "%{http_code}" \
     -X POST "${API_URL}/stats/sync" \
-    -H "Authorization: Bearer ${TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"stats":{"lifetime":{"calls":42,"tokensSaved":99000,"byTool":{},"byDay":{}}}}' \
     || echo "000")
@@ -98,8 +103,7 @@ else
 
   # Derive userId from token (first 8 chars as a smoke proxy — real impl uses DB lookup)
   # Instead, hit the aggregate endpoint to get the userId
-  AGG=$(curl -sf \
-    -H "Authorization: Bearer ${TOKEN}" \
+  AGG=$(auth_curl -sf \
     "${API_URL}/stats/aggregate" || echo "{}")
   USER_ID=$(echo "$AGG" | grep -o '"user_id":"[^"]*"' | cut -d'"' -f4 || echo "")