agentic-relay 4.0.0 → 4.1.1

package/bin/lib/zip.mjs

@@ -0,0 +1,139 @@
+/**
+ * Pure-JS zip extraction — no system `unzip` dependency (Windows ships none).
+ *
+ * Deliberately minimal: reads the END-OF-CENTRAL-DIRECTORY record and walks the
+ * central directory (never trusting local headers for sizes — that's what makes
+ * archives written with data descriptors / flag bit 3 work), then inflates each
+ * entry with node:zlib. Supported: store (method 0) and deflate (method 8).
+ * Rejected with explicit errors: zip64, encrypted entries, other methods.
+ *
+ * Security posture (matches the old `unzip` path, or stricter):
+ *  - zip-slip guard runs over ALL entry names before anything is written
+ *  - symlink entries are materialized as regular files (no link-then-write-through)
+ *  - nothing from the archive is ever executed
+ */
+
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join, resolve, sep } from "path";
+import { inflateRawSync } from "zlib";
+
+const EOCD_SIG = 0x06054b50; // end of central directory
+const CEN_SIG = 0x02014b50; // central directory file header
+const LOC_SIG = 0x04034b50; // local file header
+const ZIP64_LOCATOR_SIG = 0x07064b50; // zip64 EOCD locator
+
+/** Reject any archive entry that escapes the destination (absolute or ../). */
+export function assertNoZipSlip(entryNames, destDir) {
+  const destRoot = resolve(destDir) + sep;
+  for (const name of entryNames) {
+    if (name.startsWith("/") || name.includes("\0")) {
+      throw new Error(`unsafe archive entry (absolute path): ${name}`);
+    }
+    const target = resolve(destDir, name);
+    if (target !== resolve(destDir) && !target.startsWith(destRoot)) {
+      throw new Error(`unsafe archive entry (path traversal / zip-slip): ${name}`);
+    }
+  }
+}
+
+/**
+ * Locate the EOCD record (scan backwards over the max 22-byte record +
+ * 65535-byte comment tail). Throws on zip64 archives and missing records.
+ */
+export function findEndOfCentralDirectory(buf) {
+  const min = Math.max(0, buf.length - 22 - 65535);
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) !== EOCD_SIG) continue;
+    const totalEntries = buf.readUInt16LE(i + 10);
+    const cdSize = buf.readUInt32LE(i + 12);
+    const cdOffset = buf.readUInt32LE(i + 16);
+    if (
+      totalEntries === 0xffff ||
+      cdSize === 0xffffffff ||
+      cdOffset === 0xffffffff ||
+      (i >= 20 && buf.readUInt32LE(i - 20) === ZIP64_LOCATOR_SIG)
+    ) {
+      throw new Error("zip64 archives are not supported");
+    }
+    return { cdOffset, cdSize, totalEntries };
+  }
+  throw new Error("invalid zip: end-of-central-directory record not found");
+}
+
+/**
+ * Walk the central directory. Sizes/offsets come from here, NEVER from local
+ * headers, so data-descriptor zips (local sizes = 0) extract correctly.
+ */
+export function listZipEntries(buf) {
+  const { cdOffset, totalEntries } = findEndOfCentralDirectory(buf);
+  const entries = [];
+  let p = cdOffset;
+  for (let n = 0; n < totalEntries; n++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== CEN_SIG) {
+      throw new Error("invalid zip: corrupt central directory");
+    }
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const compressedSize = buf.readUInt32LE(p + 20);
+    const uncompressedSize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localHeaderOffset = buf.readUInt32LE(p + 42);
+    const name = buf.toString("utf-8", p + 46, p + 46 + nameLen);
+    if (flags & 0x1) {
+      throw new Error(`encrypted zip entries are not supported: ${name}`);
+    }
+    entries.push({
+      name,
+      method,
+      compressedSize,
+      uncompressedSize,
+      localHeaderOffset,
+      isDirectory: name.endsWith("/"),
+    });
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+/** Decompress one entry's bytes (seeks via the local header it points at). */
+export function readEntryData(buf, entry) {
+  const p = entry.localHeaderOffset;
+  if (p + 30 > buf.length || buf.readUInt32LE(p) !== LOC_SIG) {
+    throw new Error(`invalid zip: bad local header for ${entry.name}`);
+  }
+  // The local header's OWN name/extra lengths govern where data starts (its
+  // extra field can differ from the central directory's).
+  const nameLen = buf.readUInt16LE(p + 26);
+  const extraLen = buf.readUInt16LE(p + 28);
+  const start = p + 30 + nameLen + extraLen;
+  const data = buf.subarray(start, start + entry.compressedSize);
+  if (entry.method === 0) return Buffer.from(data);
+  if (entry.method === 8) return inflateRawSync(data);
+  throw new Error(`unsupported zip compression method ${entry.method} for ${entry.name}`);
+}
+
+/**
+ * Extract an in-memory zip buffer into destDir. Returns the list of file paths
+ * written. Validates every entry name against zip-slip BEFORE any write.
+ */
+export function extractZip(buf, destDir) {
+  const entries = listZipEntries(buf);
+  assertNoZipSlip(entries.map((e) => e.name), destDir);
+  mkdirSync(destDir, { recursive: true });
+  const placed = [];
+  for (const entry of entries) {
+    const target = join(destDir, entry.name);
+    if (entry.isDirectory) {
+      mkdirSync(target, { recursive: true });
+      continue;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    // Symlink entries (unix mode S_IFLNK in external attrs) are intentionally
+    // written as regular files containing the link target text.
+    writeFileSync(target, readEntryData(buf, entry));
+    placed.push(target);
+  }
+  return placed;
+}

package/bin/relay-core.mjs

@@ -35,9 +35,19 @@ import {
   cmdFetchSession,
 } from "./lib/commands.mjs";
 import { cmdFetch } from "./lib/fetch.mjs";
+import { cmdDoctor, fmtDoctor } from "./lib/doctor.mjs";
+import { maybeNotifyUpdate } from "./lib/update-check.mjs";
 
 const EXIT = { OK: 0, PARTIAL: 1, USAGE: 2, AUTH: 3 };
 
+function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
 const FLAGS_WITH_VALUE = new Set([
   "--api-key",
   "--context",
@@ -129,7 +139,7 @@ function fail(message, exitCode, json) {
 
 // ── human formatters ──────────────────────────────────────────────────────
 const fmtSearch = (e) => {
-  const lines = [`${e.count} capabilities for "${e.query}"`];
+  const lines = [`${e.count} capabilities for "${e.query}"${e.from_cache ? ` (cached ${e.cached_at})` : ""}`];
   for (const c of e.capabilities) {
     const price = c.clearing_price_cents ? `$${(c.clearing_price_cents / 100).toFixed(2)}` : "free";
     const rel = c.relevance != null ? c.relevance.toFixed(2) : "—";
@@ -138,6 +148,17 @@ const fmtSearch = (e) => {
     lines.push(`  ${kind} ${c.slug}  (rel ${rel}, ${price})  ${c.name}`);
     if (desc) lines.push(`        ${desc}`);
   }
+  // Surface the spend policy in human output too — agents reading --json get
+  // the full payment_context object; humans shouldn't be blind to it.
+  const p = e.payment_context;
+  if (p) {
+    const dol = (c) => (c == null ? "—" : `$${(c / 100).toFixed(2)}`);
+    lines.push(
+      `pay policy: autonomous ${p.autonomous_enabled ? "ON" : "off"}, auto-approve under ${dol(p.auto_approve_under_cents)},` +
+        ` daily cap left ${dol(p.daily_cap_remaining_cents)}, wallet: ${p.wallet?.methods?.length ? p.wallet.methods.join(",") : "none"}` +
+        `${e.from_cache ? " (cached snapshot — `agentrelay budget` for live)" : ""}`,
+    );
+  }
   return lines.join("\n");
 };
 
@@ -173,6 +194,9 @@ Payments (autonomous spend policy — server-canonical):
                                      [--require-human-over=<$>] [--per-session-cap=<$>]
   agentrelay connect-wallet           (wallet connect is set up in the dashboard)
 
+Diagnostics:
+  agentrelay doctor                  check node/key/API/npm-prefix/PATH health (--json)
+
 Deliverables (after a paid session returns a delivery object):
   agentrelay fetch --session <id>    [--message "<m>"] [dest]   ONE-STEP after payment:
                                      drives a turn to mint a fresh signed URL, then
@@ -204,14 +228,17 @@ async function main() {
     );
   }
   if (cmd === "version" || flags.version) {
-    let v = "unknown";
-    try {
-      v = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
-    } catch { /* fall back to "unknown" */ }
-    process.stdout.write(`agentrelay ${v}\n`);
+    process.stdout.write(`agentrelay ${packageVersion()}\n`);
     process.exit(EXIT.OK);
   }
 
+  // Non-blocking: nag from cached state, refresh in a detached child ≤1×/24h.
+  try {
+    maybeNotifyUpdate({ currentVersion: packageVersion() });
+  } catch {
+    /* never let the update nag break a command */
+  }
+
   let shared;
   try {
     shared = buildShared(flags);
@@ -220,9 +247,9 @@ async function main() {
   }
   const json = shared.json;
 
-  // cache and raw-URL fetch are the only commands that don't need a key.
-  // `fetch --session` calls the session API, so it does need one.
-  const keylessCmd = cmd === "cache" || (cmd === "fetch" && !flags.session);
+  // cache, raw-URL fetch, and doctor don't need a key (doctor resolves and
+  // reports on the key itself). `fetch --session` calls the session API.
+  const keylessCmd = cmd === "cache" || cmd === "doctor" || (cmd === "fetch" && !flags.session);
   if (!keylessCmd && !shared.apiKey) {
     return fail(
       "no API key — set --api-key, $AGENT_RELAY_API_KEY, or ~/.config/agent-relay/credentials.json",
@@ -318,6 +345,12 @@ async function main() {
         });
       }
 
+      case "doctor": {
+        const payload = await cmdDoctor({ ...shared, apiKey: flags["api-key"] || null });
+        const exitCode = payload.exit_code;
+        return emit(payload, { json, ok: payload.doctor_ok, exitCode, human: fmtDoctor });
+      }
+
       case "cache": {
         const payload = cmdCache(positionals[0], positionals[1], { ...shared, file: flags.file || null });
         const human = Array.isArray(payload.specs)
@@ -333,7 +366,7 @@ async function main() {
 
       default:
         return fail(
-          `unknown command "${cmd}" (session|search|feedback|cache|budget|connect-wallet|fetch)`,
+          `unknown command "${cmd}" (session|search|feedback|cache|budget|connect-wallet|fetch|doctor)`,
           EXIT.USAGE,
           json,
         );

package/bin/test/cache.test.mjs

@@ -6,11 +6,11 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, rmSync, existsSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Cache } from "../lib/cache.mjs";
-import { resolveCapability } from "../lib/commands.mjs";
+import { resolveCapability, cmdCache } from "../lib/commands.mjs";
 
 const ISO = "2026-05-24T00:00:00.000Z";
 
@@ -69,3 +69,45 @@ test("resolveCapability: falls back to the banked spec's ids (no network)", asyn
     assert.equal(r.name, "A Tool");
   });
 });
+
+test("cache put: soft contract warnings (missing session_id/summary/features), still stores", () => {
+  withCache((dir, cache) => {
+    const f = join(dir, "min.json");
+    writeFileSync(f, JSON.stringify({ slug: "bare-tool", name: "Bare" }));
+    const r = cmdCache("put", "bare-tool", { cacheDir: dir, file: f });
+    assert.equal(r.stored, true);
+    assert.equal(r.warnings.length, 3);
+    assert.match(r.warnings.join(" "), /session_id/);
+    assert.match(r.warnings.join(" "), /summary/);
+    assert.match(r.warnings.join(" "), /features/);
+    assert.ok(cache.readSpec("bare-tool")); // warned, but banked anyway
+
+    // A contract-complete spec yields no warnings.
+    writeFileSync(
+      f,
+      JSON.stringify({
+        slug: "full-tool",
+        session_id: "s-1",
+        summary: "maps the surface",
+        features: [{ feature: "x", how: "y", status: "surface_only" }],
+      }),
+    );
+    const r2 = cmdCache("put", "full-tool", { cacheDir: dir, file: f });
+    assert.deepEqual(r2.warnings, []);
+    assert.ok(cache.readSpec("full-tool"));
+
+    // features[] present but entries missing status → one targeted warning.
+    writeFileSync(
+      f,
+      JSON.stringify({
+        slug: "statusless-tool",
+        session_id: "s-2",
+        summary: "mapped",
+        features: [{ feature: "x", how: "y" }, { feature: "z", how: "w", status: "coded" }],
+      }),
+    );
+    const r3 = cmdCache("put", "statusless-tool", { cacheDir: dir, file: f });
+    assert.equal(r3.warnings.length, 1);
+    assert.match(r3.warnings[0], /1 feature\(s\) missing status/);
+  });
+});

package/bin/test/doctor.test.mjs

@@ -0,0 +1,76 @@
+/**
+ * Tests for `agentrelay doctor` (pure pieces) and the sysenv probes that are
+ * testable without touching the real npm install.
+ * Run: `node --test bin/test/doctor.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { sep } from "node:path";
+import { checkNodeVersion, summarize, fmtDoctor } from "../lib/doctor.mjs";
+import { dirOnPath, npmGlobalBinDir, globalBinShimPath, isEphemeralBin } from "../lib/sysenv.mjs";
+
+test("checkNodeVersion: >=18 ok, <18 fail", () => {
+  assert.equal(checkNodeVersion("18.0.0").status, "ok");
+  assert.equal(checkNodeVersion("23.11.0").status, "ok");
+  assert.equal(checkNodeVersion("16.20.2").status, "fail");
+  assert.match(checkNodeVersion("16.20.2").detail, /needs Node >= 18/);
+});
+
+test("summarize: warns don't fail the doctor, fails do", () => {
+  const okWarn = summarize([
+    { status: "ok" },
+    { status: "warn" },
+  ]);
+  assert.equal(okWarn.ok, true);
+  assert.equal(okWarn.exitCode, 0);
+
+  const withFail = summarize([{ status: "ok" }, { status: "fail" }]);
+  assert.equal(withFail.ok, false);
+  assert.equal(withFail.exitCode, 1);
+});
+
+test("fmtDoctor renders one line per check + a verdict line", () => {
+  const out = fmtDoctor({
+    checks: [
+      { status: "ok", label: "Node.js version", detail: "v20.0.0" },
+      { status: "warn", label: "API key", detail: "not found" },
+    ],
+    doctor_ok: true,
+  });
+  const lines = out.split("\n");
+  assert.equal(lines.length, 3);
+  assert.match(lines[0], /^✓ /);
+  assert.match(lines[1], /^! /);
+  assert.match(lines[2], /no blocking problems/);
+});
+
+test("dirOnPath: exact component match, trailing-slash tolerant", () => {
+  const delim = process.platform === "win32" ? ";" : ":";
+  const pathVar = ["/usr/bin", "/opt/homebrew/bin/"].join(delim);
+  assert.equal(dirOnPath("/opt/homebrew/bin", pathVar), true);
+  assert.equal(dirOnPath("/usr/bin", pathVar), true);
+  assert.equal(dirOnPath("/usr/local/bin", pathVar), false);
+  assert.equal(dirOnPath(null, pathVar), false);
+});
+
+test("npmGlobalBinDir/globalBinShimPath shape per platform", () => {
+  const prefix = process.platform === "win32" ? "C:\\npm" : "/opt/homebrew";
+  const binDir = npmGlobalBinDir(prefix);
+  const shim = globalBinShimPath(prefix, "agentrelay");
+  if (process.platform === "win32") {
+    assert.equal(binDir, prefix);
+    assert.ok(shim.endsWith("agentrelay.cmd"));
+  } else {
+    assert.equal(binDir, `${prefix}/bin`);
+    assert.ok(shim.endsWith("/bin/agentrelay"));
+  }
+  assert.equal(npmGlobalBinDir(null), null);
+});
+
+test("isEphemeralBin flags npx-cache paths and dangling symlinks", () => {
+  const npxBin = ["", "Users", "x", ".npm", "_npx", "ab12", "node_modules", ".bin", "agentrelay"].join(sep);
+  assert.equal(isEphemeralBin(npxBin, "/tmp/pkg"), true);
+  // A path that doesn't exist → realpath throws → treated as not-usable.
+  assert.equal(isEphemeralBin("/definitely/not/a/real/bin", "/tmp/pkg"), true);
+  assert.equal(isEphemeralBin(null, "/tmp/pkg"), false);
+});

package/bin/test/fetch.test.mjs

@@ -16,7 +16,6 @@ import {
   sha256Hex,
   inferSlug,
   uniqueDir,
-  zipEntriesFromListing,
   assertNoZipSlip,
   cmdFetch,
 } from "../lib/fetch.mjs";
@@ -41,20 +40,6 @@ test("inferSlug from filename and URL", () => {
   assert.equal(inferSlug("not a url"), "deliverable");
 });
 
-test("zipEntriesFromListing parses unzip -l output", () => {
-  const listing = [
-    "Archive:  x.zip",
-    "  Length      Date    Time    Name",
-    "---------  ---------- -----   ----",
-    "       12  2026-06-03 10:00   skill/SKILL.md",
-    "        0  2026-06-03 10:00   skill/",
-    "---------                     -------",
-    "       12                     2 files",
-  ].join("\n");
-  const entries = zipEntriesFromListing(listing);
-  assert.deepEqual(entries, ["skill/SKILL.md", "skill/"]);
-});
-
 test("assertNoZipSlip rejects traversal and absolute paths", () => {
   const dest = join(tmpdir(), "dest");
   assert.throws(() => assertNoZipSlip(["../escape.sh"], dest), /zip-slip|traversal/);

package/bin/test/install-args.test.mjs

@@ -0,0 +1,68 @@
+/**
+ * Tests for installer argument parsing (bin/lib/install-args.mjs) — focused on
+ * the `--api-key= <key>` space-typo rescue observed in the field.
+ * Run: `node --test bin/test/install-args.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseInstallArgs } from "../lib/install-args.mjs";
+
+const KEY = "am_live_abc123def456";
+
+test("--api-key=KEY parses", () => {
+  const { flags, warnings } = parseInstallArgs([`--api-key=${KEY}`, "--all"]);
+  assert.equal(flags.apiKey, KEY);
+  assert.equal(flags.all, true);
+  assert.deepEqual(warnings, []);
+});
+
+test("--api-key KEY (space-separated) parses", () => {
+  const { flags, warnings } = parseInstallArgs(["--api-key", KEY]);
+  assert.equal(flags.apiKey, KEY);
+  assert.deepEqual(warnings, []);
+});
+
+test("--api-key= KEY (the space typo) rescues the bare key with a warning", () => {
+  const { flags, warnings } = parseInstallArgs(["--all", "--api-key=", KEY]);
+  assert.equal(flags.apiKey, KEY);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /no space/);
+});
+
+test("bare am_live_* positional alone is rescued with a warning", () => {
+  const { flags, warnings } = parseInstallArgs([KEY, "--all"]);
+  assert.equal(flags.apiKey, KEY);
+  assert.equal(warnings.length, 1);
+});
+
+test("empty --api-key= with no rescue positional warns and stays null", () => {
+  const { flags, warnings } = parseInstallArgs(["--api-key="]);
+  assert.equal(flags.apiKey, "");
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /no value/);
+});
+
+test("non-key positionals are not adopted", () => {
+  const { flags, warnings } = parseInstallArgs(["hello", "--all"]);
+  assert.equal(flags.apiKey, null);
+  assert.deepEqual(warnings, []);
+});
+
+test("space-form value is not double-counted as a rescue positional", () => {
+  const { flags, warnings } = parseInstallArgs(["--api-key", KEY]);
+  assert.equal(flags.apiKey, KEY);
+  assert.deepEqual(warnings, []);
+});
+
+test("targets / librechat / legacy flags are unchanged", () => {
+  const { flags } = parseInstallArgs([
+    "--target=claude, codex",
+    "--librechat=/tmp/librechat.yaml",
+    "--claude",
+    "--project",
+  ]);
+  assert.deepEqual(flags.targets, ["claude", "codex"]);
+  assert.equal(flags.librechat, "/tmp/librechat.yaml");
+  assert.equal(flags.legacyClaude, true);
+  assert.equal(flags.project, true);
+});

package/bin/test/session.test.mjs

@@ -65,8 +65,12 @@ test("deliveryToFetchArgs: maps a delivery object to cmdFetch args (tolerant of
       filename: "x.zip",
       slug: "gstack",
     }),
-    { url: "https://store/x.zip", checksum: "abc123", filename: "x.zip", dest: null },
+    // dest defaults to ./<delivery.slug>/ (the documented contract); an
+    // explicit dest always wins.
+    { url: "https://store/x.zip", checksum: "abc123", filename: "x.zip", dest: "./gstack" },
   );
+  // a hostile slug is slugified — it can't traverse out of the working dir
+  assert.equal(deliveryToFetchArgs({ download_url: "https://s/x", slug: "../../etc" }).dest, "./etc");
   // variant keys + dest override
   assert.deepEqual(
     deliveryToFetchArgs({ url: "https://store/y", checksum: "def" }, { dest: "./out" }),

package/bin/test/update-check.test.mjs

@@ -0,0 +1,56 @@
+/**
+ * Tests for the async update notifier (bin/lib/update-check.mjs) — the pure
+ * pieces: semver compare, state round-trip, suppression predicate.
+ * Run: `node --test bin/test/update-check.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+import { compareSemver, shouldSuppress, readState, writeState } from "../lib/update-check.mjs";
+
+test("compareSemver orders numerically, not lexically", () => {
+  assert.equal(compareSemver("1.2.3", "1.2.3"), 0);
+  assert.equal(compareSemver("1.10.0", "1.2.0"), 1); // lexical would say 1.10 < 1.2
+  assert.equal(compareSemver("4.0.0", "3.9.9"), 1);
+  assert.equal(compareSemver("3.8.5", "4.0.0"), -1);
+  assert.equal(compareSemver("1.2", "1.2.0"), 0);
+});
+
+test("state round-trips through a custom path", () => {
+  const root = mkdtempSync(join(tmpdir(), "agent-relay-update-"));
+  try {
+    const p = join(root, "nested", "update-check.json");
+    const state = { last_check_ts: "2026-06-11T00:00:00.000Z", latest_version: "9.9.9" };
+    assert.equal(writeState(state, p), true);
+    assert.deepEqual(readState(p), state);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("readState returns null for missing/corrupt files", () => {
+  assert.equal(readState("/nonexistent/path/update.json"), null);
+});
+
+const TTY_BASE = { env: {}, stderrIsTTY: true, binPath: "/usr/local/bin/agentrelay" };
+
+test("suppression: env kill-switches", () => {
+  assert.equal(shouldSuppress({ ...TTY_BASE, env: { AGENT_RELAY_NO_UPDATE_CHECK: "1" } }), true);
+  assert.equal(shouldSuppress({ ...TTY_BASE, env: { NO_UPDATE_NOTIFIER: "1" } }), true);
+  assert.equal(shouldSuppress({ ...TTY_BASE, env: { CI: "true" } }), true);
+});
+
+test("suppression: non-TTY stderr (piped/scripted runs)", () => {
+  assert.equal(shouldSuppress({ ...TTY_BASE, stderrIsTTY: false }), true);
+});
+
+test("suppression: running from an npx cache", () => {
+  const npxPath = ["", "Users", "x", ".npm", "_npx", "abc123", "node_modules", ".bin", "agentrelay"].join(sep);
+  assert.equal(shouldSuppress({ ...TTY_BASE, binPath: npxPath }), true);
+});
+
+test("not suppressed: interactive TTY run from a real install", () => {
+  assert.equal(shouldSuppress(TTY_BASE), false);
+});