agentic-relay 3.8.5 → 4.1.0

package/bin/lib/update-check.mjs

@@ -0,0 +1,121 @@
+/**
+ * Async update notifier (the Vercel/update-notifier pattern, zero-dep).
+ *
+ * The CLI never blocks on the network: each run reads a tiny local state file
+ * and prints a one-line stderr nag if a newer version was seen on a PREVIOUS
+ * run; when the state is older than 24h it spawns a detached, unref'd child
+ * (this module with --refresh) that fetches the registry and rewrites the
+ * state for next time.
+ *
+ * Suppressed when: AGENT_RELAY_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER / CI env
+ * vars are set, stderr isn't a TTY (don't pollute piped/scripted runs), or the
+ * CLI is running out of an ephemeral npx cache (npx users get @latest anyway).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { join, dirname, sep } from "path";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+export const STATE_PATH = join(homedir(), ".config", "agent-relay", "update-check.json");
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const SELF_PATH = fileURLToPath(import.meta.url);
+
+/** Numeric-dotted semver compare: 1 if a > b, -1 if a < b, 0 if equal. */
+export function compareSemver(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da !== db) return da > db ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * Pure suppression predicate (exported for tests). env/tty/binPath injected.
+ */
+export function shouldSuppress({ env, stderrIsTTY, binPath }) {
+  if (env.AGENT_RELAY_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI) return true;
+  if (!stderrIsTTY) return true;
+  if (binPath) {
+    let real = binPath;
+    try {
+      real = realpathSync(binPath);
+    } catch {
+      /* keep as-is */
+    }
+    if (real.includes(`${sep}_npx${sep}`) || binPath.includes(`${sep}_npx${sep}`)) return true;
+  }
+  return false;
+}
+
+export function readState(statePath = STATE_PATH) {
+  try {
+    return JSON.parse(readFileSync(statePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(state, statePath = STATE_PATH) {
+  try {
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Called at the top of every CLI run. Never throws, never blocks: prints the
+ * nag from cached state and (at most once per 24h) spawns the background
+ * refresh.
+ */
+export function maybeNotifyUpdate({ currentVersion, binPath = process.argv[1] }) {
+  try {
+    if (shouldSuppress({ env: process.env, stderrIsTTY: Boolean(process.stderr.isTTY), binPath })) {
+      return;
+    }
+    const state = readState();
+    if (state?.latest_version && compareSemver(state.latest_version, currentVersion) > 0) {
+      process.stderr.write(
+        `agentrelay ${state.latest_version} is available (you have ${currentVersion}) — npm i -g agentic-relay\n`,
+      );
+    }
+    const last = state?.last_check_ts ? Date.parse(state.last_check_ts) : 0;
+    if (!Number.isFinite(last) || Date.now() - last > CHECK_INTERVAL_MS) {
+      spawn(process.execPath, [SELF_PATH, "--refresh"], { detached: true, stdio: "ignore" }).unref();
+    }
+  } catch {
+    // The nag must never break a command.
+  }
+}
+
+/** Background refresh: fetch the registry, persist state, exit. */
+async function refresh() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetch("https://registry.npmjs.org/agentic-relay/latest", {
+      signal: controller.signal,
+    });
+    if (!res.ok) return;
+    const data = await res.json();
+    if (data?.version) {
+      writeState({ last_check_ts: new Date().toISOString(), latest_version: data.version });
+    }
+  } catch {
+    // Offline/registry down — try again next interval.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Self-run refresh mode (spawned detached by maybeNotifyUpdate).
+if (process.argv[1] === SELF_PATH && process.argv[2] === "--refresh") {
+  refresh();
+}

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

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 
 /**
- * agentrelay (CLI core) — token-cheap, parallel agent consulting for coding workflows.
+ * agentrelay (CLI core) — live agent sessions, payments, and deliverable fetch.
  *
- * Wraps the AttentionMarket REST API so a coding agent can consult expert
- * "solutions-engineer" capability agents without flooding its context with raw
- * transcripts. The multi-turn qualify→deliver loop, fan-out, and caching run
- * HERE (in this process), and only compact Deliverables come back.
+ * Wraps the AttentionMarket REST API so a coding agent can converse with expert
+ * "solutions-engineer" capability agents. The caller (a host subagent, or the
+ * main agent directly) drives the conversation via the session primitives and
+ * banks compact specs in the on-disk cache; raw transcripts stay out of the
+ * main context.
  *
  * Commands:
- *   agentrelay search <query>        broad discovery (cheap; safe in main context)
- *   agentrelay consult <slug>        run one agent's full loop → a Deliverable
- *   agentrelay consult-batch         fan-out, parallel, one consolidated result
- *   agentrelay cache ls|show|clear   inspect/manage the on-disk spec cache
+ *   agentrelay search <query>          broad discovery (cheap; safe in main context)
+ *   agentrelay session start|send|pay|end   drive a live consult
+ *   agentrelay cache ls|show|put|clear inspect/manage the on-disk spec cache
+ *   agentrelay fetch                   download + verify + unpack a paid deliverable
  *
  * Output: a `{ ok, ...payload, errors: [] }` envelope. --json forces machine
  * output (auto-on when stdout is not a TTY). Exit codes: 0 ok, 1 partial,
@@ -26,8 +27,6 @@ import { readFileSync } from "fs";
 import { resolveApiKey } from "./lib/config.mjs";
 import {
   cmdSearch,
-  cmdConsult,
-  cmdConsultBatch,
   cmdSession,
   cmdFeedback,
   cmdCache,
@@ -36,22 +35,26 @@ 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",
   "--cache-dir",
   "--timeout",
-  "--max-turns",
-  "--concurrency",
   "--max",
   "--user-context",
-  "--want",
-  "--want-file",
-  "--agents",
-  "--driver",
   "--initial",
   "--message",
   "--data",
@@ -108,8 +111,6 @@ function buildShared(flags) {
     noCache: Boolean(flags["no-cache"]),
     refresh: Boolean(flags.refresh),
     timeoutMs: (Number(flags.timeout) || 120) * 1000,
-    maxTurns: Number(flags["max-turns"]) || 6,
-    concurrency: Number(flags.concurrency) || 5,
     quiet: Boolean(flags.quiet),
     verbose: Boolean(flags.verbose),
     context: loadContext(flags.context),
@@ -163,19 +164,6 @@ const fmtBudget = (e) => {
   ].join("\n");
 };
 
-const fmtDeliverable = (d) => {
-  const lines = [`▸ ${d.name} (${d.slug})${d.cached ? " [cached]" : ""}`];
-  if (d.verdict) lines.push(`  verdict: ${d.verdict}`);
-  if (d.install?.length) lines.push(`  install: ${d.install.join(" && ")}`);
-  if (d.endpoints?.length) lines.push(`  endpoints: ${d.endpoints.map((x) => x.name || x.url).join(", ")}`);
-  if (d.snippets?.length) lines.push(`  snippets: ${d.snippets.map((s) => s.path || s.desc || s.lang).join(", ")}`);
-  if (d.gotchas?.length) lines.push(`  gotchas: ${d.gotchas.join("; ")}`);
-  if (d.free_tier) lines.push(`  free tier: ${d.free_tier}`);
-  if (d.docs?.length) lines.push(`  docs: ${d.docs.join(" ")}`);
-  lines.push(`  (${d.turns} turns, ~${d.tokens_estimate} tokens)`);
-  return lines.join("\n");
-};
-
 const HELP = `agentrelay — converse with capability agents while you build.
 
 Conversation (LLM-driven — drive these from a subagent, or directly when you're stuck):
@@ -195,6 +183,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
@@ -202,12 +193,8 @@ Deliverables (after a paid session returns a delivery object):
   agentrelay fetch <download_url> [dest]  [--checksum <sha256>] [--filename <name>]
                                      raw-URL download + unpack (never executes anything)
 
-Template fallback (code-driven, no LLM — distilled result):
-  agentrelay consult <slug>           --want <s> [--context f.json] [--deliver-now] [--refresh]
-  agentrelay consult-batch            --agents a,b,c (--want <s> | --want-file w.json) [--concurrency 5]
-
 Global: --api-key <k> --json --context <f> --cache-dir <d> --no-cache
-        --timeout <sec> --max-turns <n> --concurrency <n> --quiet --verbose
+        --timeout <sec> --quiet --verbose
 
 Key: --api-key | $AGENT_RELAY_API_KEY | ~/.config/agent-relay/credentials.json`;
 
@@ -221,15 +208,26 @@ async function main() {
     process.stdout.write(HELP + "\n");
     process.exit(cmd ? EXIT.OK : EXIT.USAGE);
   }
+  if (cmd === "consult" || cmd === "consult-batch") {
+    return fail(
+      `"${cmd}" was removed in v4 — drive a live session instead: ` +
+        "`agentrelay session start <slug>` → `session send` → `session end` (see SKILL.md)",
+      EXIT.USAGE,
+      Boolean(flags.json) || !process.stdout.isTTY,
+    );
+  }
   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);
@@ -238,9 +236,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",
@@ -263,45 +261,6 @@ async function main() {
         return emit(payload, { json, human: fmtSearch });
       }
 
-      case "consult": {
-        const slug = positionals[0];
-        if (!slug) return fail("usage: agentrelay consult <slug> --want <str>", EXIT.USAGE, json);
-        const payload = await cmdConsult(slug, {
-          ...shared,
-          want: flags.want || null,
-          driver: flags.driver || null,
-          deliverNow: Boolean(flags["deliver-now"]),
-          raw: Boolean(flags.raw),
-        });
-        return emit(payload, { json, human: (e) => fmtDeliverable(e.deliverable) });
-      }
-
-      case "consult-batch": {
-        const payload = await cmdConsultBatch({
-          ...shared,
-          agents: flags.agents ? String(flags.agents).split(",").map((s) => s.trim()).filter(Boolean) : null,
-          want: flags.want || null,
-          wantFile: flags["want-file"] || null,
-          driver: flags.driver || null,
-          deliverNow: Boolean(flags["deliver-now"]),
-          raw: Boolean(flags.raw),
-        });
-        const exitCode = payload.failures.length > 0 ? EXIT.PARTIAL : EXIT.OK;
-        return emit(payload, {
-          json,
-          ok: payload.failures.length === 0,
-          errors: payload.failures.map((f) => `${f.slug}: ${f.reason}`),
-          exitCode,
-          human: (e) =>
-            [
-              `consulted ${e.totals.consulted}: ${e.totals.ok} ok, ${e.totals.failed} failed ` +
-                `(${e.totals.wall_seconds}s, ~${e.totals.tokens_estimate} tokens)`,
-              ...e.deliverables.map(fmtDeliverable),
-              ...e.failures.map((f) => `✗ ${f.slug}: ${f.reason}`),
-            ].join("\n"),
-        });
-      }
-
       case "session": {
         const payload = await cmdSession(positionals[0], positionals.slice(1), {
           ...shared,
@@ -375,6 +334,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)
@@ -390,7 +355,7 @@ async function main() {
 
       default:
         return fail(
-          `unknown command "${cmd}" (session|search|consult|consult-batch|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,31 @@ 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"));
+  });
+});

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/);