agentic-relay 4.0.0 → 4.1.0

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",
@@ -173,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
@@ -204,14 +217,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 +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",
@@ -318,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)
@@ -333,7 +355,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,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/);

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);
+});

package/bin/test/zip.test.mjs

@@ -0,0 +1,212 @@
+/**
+ * Tests for the pure-JS zip extractor (bin/lib/zip.mjs). Fixture zips are
+ * hand-assembled in memory (local headers + central directory + EOCD) so we
+ * can exercise shapes the system `zip` tool won't produce — data descriptors,
+ * zip64 markers, encrypted flags. Run: `node --test bin/test/zip.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync, lstatSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deflateRawSync } from "node:zlib";
+import {
+  findEndOfCentralDirectory,
+  listZipEntries,
+  readEntryData,
+  extractZip,
+} from "../lib/zip.mjs";
+
+/**
+ * Assemble a zip from entries: [{name, data, method?, dataDescriptor?, flags?}].
+ * method: 0 store (default), 8 deflate. dataDescriptor: local sizes zeroed,
+ * flag bit 3 set, 16-byte descriptor appended after the data (the shape
+ * streaming writers produce — central directory holds the truth).
+ */
+function buildZip(entries, { zip64Eocd = false } = {}) {
+  const parts = [];
+  const central = [];
+  let offset = 0;
+
+  for (const e of entries) {
+    const name = Buffer.from(e.name, "utf-8");
+    const raw = Buffer.from(e.data ?? "", "utf-8");
+    const method = e.method ?? 0;
+    const payload = method === 8 ? deflateRawSync(raw) : raw;
+    const useDD = Boolean(e.dataDescriptor);
+    const flags = (e.flags ?? 0) | (useDD ? 0x8 : 0);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(flags, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(0, 10); // time
+    local.writeUInt16LE(0, 12); // date
+    local.writeUInt32LE(0, 14); // crc (not verified by extractor)
+    local.writeUInt32LE(useDD ? 0 : payload.length, 18);
+    local.writeUInt32LE(useDD ? 0 : raw.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28); // extra len
+
+    const localOffset = offset;
+    parts.push(local, name, payload);
+    offset += local.length + name.length + payload.length;
+
+    if (useDD) {
+      const dd = Buffer.alloc(16);
+      dd.writeUInt32LE(0x08074b50, 0); // optional descriptor signature
+      dd.writeUInt32LE(0, 4); // crc
+      dd.writeUInt32LE(payload.length, 8);
+      dd.writeUInt32LE(raw.length, 12);
+      parts.push(dd);
+      offset += dd.length;
+    }
+
+    const cen = Buffer.alloc(46);
+    cen.writeUInt32LE(0x02014b50, 0);
+    cen.writeUInt16LE(20, 4); // version made by
+    cen.writeUInt16LE(20, 6); // version needed
+    cen.writeUInt16LE(flags, 8);
+    cen.writeUInt16LE(method, 10);
+    cen.writeUInt16LE(0, 12); // time
+    cen.writeUInt16LE(0, 14); // date
+    cen.writeUInt32LE(0, 16); // crc
+    cen.writeUInt32LE(payload.length, 20); // TRUE sizes live here
+    cen.writeUInt32LE(raw.length, 24);
+    cen.writeUInt16LE(name.length, 28);
+    cen.writeUInt16LE(0, 30); // extra
+    cen.writeUInt16LE(0, 32); // comment
+    cen.writeUInt16LE(0, 34); // disk start
+    cen.writeUInt16LE(0, 36); // internal attrs
+    cen.writeUInt32LE(e.externalAttrs ?? 0, 38);
+    cen.writeUInt32LE(localOffset, 42);
+    central.push(Buffer.concat([cen, name]));
+  }
+
+  const cd = Buffer.concat(central);
+  const cdOffset = offset;
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4); // disk
+  eocd.writeUInt16LE(0, 6); // cd disk
+  eocd.writeUInt16LE(zip64Eocd ? 0xffff : entries.length, 8);
+  eocd.writeUInt16LE(zip64Eocd ? 0xffff : entries.length, 10);
+  eocd.writeUInt32LE(cd.length, 12);
+  eocd.writeUInt32LE(zip64Eocd ? 0xffffffff : cdOffset, 16);
+  eocd.writeUInt16LE(0, 20); // comment len
+  return Buffer.concat([...parts, cd, eocd]);
+}
+
+function tmpDest(prefix) {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+test("stored entry round-trips", () => {
+  const buf = buildZip([{ name: "a.txt", data: "hello stored" }]);
+  const root = tmpDest("zip-stored-");
+  try {
+    const placed = extractZip(buf, join(root, "out"));
+    assert.equal(placed.length, 1);
+    assert.equal(readFileSync(placed[0], "utf-8"), "hello stored");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("deflated entry round-trips", () => {
+  const text = "deflate me ".repeat(100);
+  const buf = buildZip([{ name: "b.txt", data: text, method: 8 }]);
+  const root = tmpDest("zip-deflate-");
+  try {
+    const placed = extractZip(buf, join(root, "out"));
+    assert.equal(readFileSync(placed[0], "utf-8"), text);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("data-descriptor zip (local sizes zeroed) extracts via central directory", () => {
+  const text = "streamed entry with data descriptor";
+  const buf = buildZip([{ name: "dd.txt", data: text, method: 8, dataDescriptor: true }]);
+  // Sanity: the local header really does carry zero sizes.
+  assert.equal(buf.readUInt32LE(18), 0);
+  const entries = listZipEntries(buf);
+  assert.equal(entries[0].compressedSize > 0, true);
+  const root = tmpDest("zip-dd-");
+  try {
+    const placed = extractZip(buf, join(root, "out"));
+    assert.equal(readFileSync(placed[0], "utf-8"), text);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("nested directories are created; dir entries write no files", () => {
+  const buf = buildZip([
+    { name: "pkg/", data: "" },
+    { name: "pkg/deep/file.md", data: "# nested" },
+  ]);
+  const root = tmpDest("zip-nest-");
+  try {
+    const out = join(root, "out");
+    const placed = extractZip(buf, out);
+    assert.equal(placed.length, 1);
+    assert.ok(existsSync(join(out, "pkg", "deep", "file.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("zip-slip entry is rejected before any write", () => {
+  const buf = buildZip([
+    { name: "ok.txt", data: "fine" },
+    { name: "../evil.sh", data: "rm -rf" },
+  ]);
+  const root = tmpDest("zip-slip-");
+  try {
+    const out = join(root, "out");
+    assert.throws(() => extractZip(buf, out), /zip-slip|traversal/);
+    assert.equal(existsSync(join(out, "ok.txt")), false); // nothing written
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("zip64 EOCD markers are rejected with a clear error", () => {
+  const buf = buildZip([{ name: "x.txt", data: "x" }], { zip64Eocd: true });
+  assert.throws(() => findEndOfCentralDirectory(buf), /zip64/);
+});
+
+test("encrypted entries are rejected with a clear error", () => {
+  const buf = buildZip([{ name: "secret.txt", data: "x", flags: 0x1 }]);
+  assert.throws(() => listZipEntries(buf), /encrypted/);
+});
+
+test("unsupported compression method is rejected", () => {
+  const buf = buildZip([{ name: "lzma.bin", data: "x", method: 14 }]);
+  const entries = listZipEntries(buf);
+  assert.throws(() => readEntryData(buf, entries[0]), /unsupported zip compression method 14/);
+});
+
+test("symlink-flagged entry is materialized as a regular file", () => {
+  const S_IFLNK = 0o120000;
+  const buf = buildZip([
+    { name: "link", data: "/etc/passwd", externalAttrs: ((S_IFLNK | 0o777) << 16) >>> 0 },
+  ]);
+  const root = tmpDest("zip-symlink-");
+  try {
+    const out = join(root, "out");
+    extractZip(buf, out);
+    const st = lstatSync(join(out, "link"));
+    assert.equal(st.isSymbolicLink(), false);
+    assert.equal(st.isFile(), true);
+    assert.equal(readFileSync(join(out, "link"), "utf-8"), "/etc/passwd");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("garbage buffer fails with a clear error", () => {
+  assert.throws(() => listZipEntries(Buffer.from("definitely not a zip file")), /end-of-central-directory/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-relay",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Install Agent Relay AI search across 17+ agents — Claude Code, Codex, Cursor, Gemini CLI, Goose, Windsurf, Cline, BoltAI, Claude Desktop, VS Code, Amazon Q, Roo Code, Witsy, LibreChat, OpenClaw, Tome, Raycast — plus the `agentrelay` CLI for live agent sessions, payments, and deliverable fetch",
   "bin": {
     "agentrelay": "bin/cli.mjs"

package/skill/SKILL.md

@@ -229,6 +229,7 @@ Score rubric: a confidently-wrong claim (a 404'd endpoint served as live, a fals
 ## Known gotchas (seeded from real runs)
 
 - **Don't truncate `--json` search output.** Piping `agentrelay search … --json | head -N` cuts off `payment_context`, which sits after the (long) capabilities array — so the agent never sees the live pay policy and falls back to a wrong default. Read the whole JSON.
+- **A cached search's `payment_context` is a snapshot, not live.** When the search result has `from_cache: true`, its `payment_context` dates from `cached_at` (search cache TTL is 1h). For an actual pay decision, read `agentrelay budget` or re-run the search with `--refresh`.
 - **Never assert pay posture from memory.** Run `agentrelay budget` or read `payment_context` before any statement about whether autonomous pay is on. (A test agent claimed "off by default" while the live setting was on with a $5 auto-approve.)
 - **`deliverable_complete` is not a stop command.** Continue the session if you still need something it didn't include.
 - **Don't reconstruct the workflow from CLAUDE.md.** It's a thin map; this skill is the manual. If you're doing Agent Relay work, you should have loaded this file.