agent-yes 1.300.3 → 1.300.4

package/dist/{terminal-DviH1E3C.js → terminal-DEXrWOa9.js}

@@ -98,7 +98,7 @@ async function cmdTermMint(args) {
 	if (flags.ro && flags.interactive) throw new Error("--ro and --interactive are mutually exclusive");
 	const ttlSec = parseTtlSec(typeof flags.ttl === "string" ? flags.ttl : "15m");
 	const canSend = flags.interactive === true;
-	const { mintScopedTermToken } = await import("./serve-DVoYVgBo.js");
+	const { mintScopedTermToken } = await import("./serve-F5tXYO0-.js");
 	const r = await mintScopedTermToken(pid, {
 		ttlSec,
 		canSend
@@ -135,4 +135,4 @@ async function cmdTerm(args) {
 
 //#endregion
 export { cmdTerm };
-//# sourceMappingURL=terminal-DviH1E3C.js.map
+//# sourceMappingURL=terminal-DEXrWOa9.js.map

package/dist/trayApp-0RVjo43f.js

@@ -0,0 +1,5 @@
+import "./versionChecker-DeQEhRGB.js";
+import "./rustBinary-CJXUPUWd.js";
+import { a as trayHiddenMarker, i as launchTray, n as hasDesktop, r as isTrayHidden, t as cmdTray } from "./trayApp-BUXx7cES.js";
+
+export { cmdTray };

package/dist/{trayApp-PJrwfyDs.js → trayApp-BUXx7cES.js}

@@ -1,4 +1,4 @@
-import { o as findTrayLauncher } from "./rustBinary-gI_r3g9K.js";
+import { c as findTrayLauncher } from "./rustBinary-CJXUPUWd.js";
 import { t as agentYesHome } from "./agentYesHome-BNtn19J4.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -97,4 +97,4 @@ async function cmdTray(args) {
 
 //#endregion
 export { trayHiddenMarker as a, launchTray as i, hasDesktop as n, isTrayHidden as r, cmdTray as t };
-//# sourceMappingURL=trayApp-PJrwfyDs.js.map
+//# sourceMappingURL=trayApp-BUXx7cES.js.map

package/dist/{ts--JmSY117.js → ts-CRbycTni.js}

@@ -1,6 +1,6 @@
 import { n as __esmMin, r as __exportAll } from "./chunk-cZBX9HZv.js";
 import { n as logger, t as addTransport } from "./logger-CDIsZ-Pp.js";
-import { i as getInstalledPackage } from "./versionChecker-CCGSbjio.js";
+import { i as getInstalledPackage } from "./versionChecker-DeQEhRGB.js";
 import { t as agentYesHome } from "./agentYesHome-BNtn19J4.js";
 import { u as removeControlCharacters } from "./todoAutomation-CbVVS4re.js";
 import { i as shouldUseLock, r as releaseLock, t as acquireLock } from "./runningLock-BOIPD_Vs.js";
@@ -24,7 +24,7 @@ import sflow from "sflow";
 import xterm from "@xterm/headless";
 import { createServer } from "net";
 import { execSync as execSync$1 } from "node:child_process";
-import { accessSync, constants as constants$1, existsSync as existsSync$1, statSync as statSync$1 } from "node:fs";
+import { accessSync as accessSync$1, constants as constants$1, existsSync as existsSync$1, statSync as statSync$1 } from "node:fs";
 import path$1 from "node:path";
 import os$1 from "node:os";
 import { readFile as readFile$1 } from "node:fs/promises";
@@ -897,7 +897,7 @@ async function applyAgentNice(pid, env = process.env) {
 function isExecutableFile(candidate) {
 	try {
 		if (!statSync$1(candidate).isFile()) return false;
-		accessSync(candidate, constants$1.X_OK);
+		accessSync$1(candidate, constants$1.X_OK);
 		return true;
 	} catch {
 		return false;
@@ -2086,7 +2086,7 @@ async function agentYes({ cli, cliArgs = [], skipPermissions = false, prompt, ro
 	}, 100);
 	const cleanupHeartbeat = () => clearInterval(heartbeatInterval);
 	shell.onExit(cleanupHeartbeat);
-	const { startParentPingLoop } = await import("./parentPingLoop-Bh3KuFcW.js");
+	const { startParentPingLoop } = await import("./parentPingLoop-9T4Pzp6c.js");
 	const parentPingLoop = startParentPingLoop({
 		parentPid,
 		selfWrapperPid: process.pid,
@@ -2349,4 +2349,4 @@ function sleep(ms) {
 
 //#endregion
 export { hasTodoStore as a, permissionBadge as c, answerAsk as i, AgentContext as l, agentYes as n, listAsks as o, config as r, listAsksForProject as s, CLIS_CONFIG as t, CLAUDE_SESSION_PIN_ENV as u };
-//# sourceMappingURL=ts--JmSY117.js.map
+//# sourceMappingURL=ts-CRbycTni.js.map

package/dist/{versionChecker-CCGSbjio.js → versionChecker-DeQEhRGB.js}

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 
 //#region package.json
 var name = "agent-yes";
-var version = "1.300.3";
+var version = "1.300.4";
 
 //#endregion
 //#region ts/versionChecker.ts
@@ -285,4 +285,4 @@ async function displayVersion() {
 
 //#endregion
 export { versionString as a, getInstalledPackage as i, compareVersions as n, displayVersion as r, checkAndAutoUpdate as t };
-//# sourceMappingURL=versionChecker-CCGSbjio.js.map
+//# sourceMappingURL=versionChecker-DeQEhRGB.js.map

package/dist/{webrtcRemote-Cd4vTrgv.js → webrtcRemote-Cy5kB8aR.js}

@@ -36,6 +36,78 @@ function signalingFailureHint(cause, probe, host) {
 	}
 }
 
+//#endregion
+//#region ts/webrtcSignal.ts
+var ConnectError = class extends Error {
+	constructor(phase, message) {
+		super(message);
+		this.phase = phase;
+		this.name = "ConnectError";
+	}
+};
+/** Classify one signaling frame against the current state. */
+function reduceSignal(state, m) {
+	if (!m || typeof m !== "object") return { kind: "ignore" };
+	switch (m.type) {
+		case "welcome":
+			if (m.hostPresent === false) return {
+				kind: "fail",
+				error: new ConnectError("no-host", "the room is open but no host is attached to it")
+			};
+			return { kind: "ignore" };
+		case "offer":
+			if (state.offered) return { kind: "duplicate-offer" };
+			return {
+				kind: "offer",
+				sdp: m.sdp,
+				iceServers: m.iceServers || [],
+				from: m.from
+			};
+		case "candidate": return {
+			kind: "candidate",
+			candidate: m.candidate,
+			queue: !state.offered
+		};
+		default: return { kind: "ignore" };
+	}
+}
+/** The error for a socket that closed before the channel was confirmed. */
+function closeError(state, code, reason) {
+	const why = `signaling closed (code ${code}${reason ? `: ${reason}` : ""})`;
+	if (!state.opened) return new ConnectError("ws-not-open", `${why} before the socket opened`);
+	if (code === 1008 || reason) return new ConnectError("rejected", why);
+	if (!state.offered) return new ConnectError("no-host", `${why} before the host offered`);
+	return new ConnectError("ice-timeout", `${why} during the WebRTC handshake`);
+}
+/** The error for the connect deadline expiring. */
+function timeoutError(state, timeoutMs) {
+	const s = `${Math.round(timeoutMs / 1e3)}s`;
+	if (!state.opened) return new ConnectError("ws-not-open", `signaling did not open within ${s}`);
+	if (!state.offered) return new ConnectError("no-host", `no host answered the join within ${s}`);
+	return new ConnectError("ice-timeout", `no WebRTC data channel came up within ${s}`);
+}
+/** The error for a WebSocket `error` event. */
+function socketError(state, detail) {
+	return state.opened ? new ConnectError("rejected", `signaling error after connect: ${detail}`) : new ConnectError("ws-not-open", `signaling error: ${detail}`);
+}
+/**
+* The operator-facing explanation. `sandboxHint` is the HTTPS-probe-derived
+* note from signalingHint.ts and is consulted ONLY for a socket that never
+* opened: every later phase proves the WebSocket upgrade worked, so blaming a
+* sandbox or proxy there would be wrong — and sent one reader down exactly
+* that path.
+*/
+function describeConnectFailure(err, host, sandboxHint) {
+	const phase = err instanceof ConnectError ? err.phase : "ws-not-open";
+	const cause = err.message;
+	switch (phase) {
+		case "no-host": return Promise.resolve(`no host in the room at ${host}: ${cause}\n  The signaling server is reachable and accepted the join — the daemon on the\n  other machine is not attached to this room. There, run \`ay share status\`:\n  if it prints a different link, the room rotated (or the daemon was\n  reinstalled) and this saved remote is stale — re-add it with the new link.`);
+		case "rejected": return Promise.resolve(`join rejected by the signaling host ${host}: ${cause}\n  The room id or secret in this saved remote no longer matches what the host\n  serves (it rotated, or the link was copied from a different machine).\n  On the host run \`ay share status\` and re-add the remote with that link.`);
+		case "ice-timeout": return Promise.resolve(`WebRTC handshake with the host behind ${host} failed: ${cause}\n  Signaling worked and the host answered, so this is not a sandbox or proxy\n  problem — the two machines could not open a data channel. Usual causes: a\n  second host answering in the same room (on the host: \`ay serve status\`,\n  and kill any stray \`ayrs serve\`), or ICE blocked between the networks.`);
+		default: return sandboxHint(cause);
+	}
+}
+
 //#endregion
 //#region ts/webrtcRemote.ts
 const CONNECT_TIMEOUT_MS = 25e3;
@@ -54,6 +126,13 @@ var WebRtcConn = class {
 	confirmedIn = false;
 	confirmedOut = false;
 	confirmed = false;
+	sig = {
+		opened: false,
+		offered: false,
+		confirmed: false
+	};
+	earlyCandidates = [];
+	warnedDuplicateHost = false;
 	sendChain = Promise.resolve();
 	recvChain = Promise.resolve();
 	idCounter = 0;
@@ -67,7 +146,7 @@ var WebRtcConn = class {
 			this.resolveReady = res;
 			this.rejectReady = rej;
 		});
-		const timer = setTimeout(() => this.rejectReady(/* @__PURE__ */ new Error(`WebRTC connect timeout after ${CONNECT_TIMEOUT_MS}ms`)), CONNECT_TIMEOUT_MS);
+		const timer = setTimeout(() => this.rejectReady(timeoutError(this.sig, CONNECT_TIMEOUT_MS)), CONNECT_TIMEOUT_MS);
 		this.ready.then(() => clearTimeout(timer), () => clearTimeout(timer));
 		this.ws = this.dial();
 	}
@@ -75,6 +154,7 @@ var WebRtcConn = class {
 		const { room, host } = this.link;
 		const ws = new WebSocket(`wss://${host}/${room}`, [SIGNAL_SUBPROTOCOL]);
 		ws.onopen = async () => {
+			this.sig.opened = true;
 			const authToken = await deriveAuthToken(this.link.s, room, host);
 			ws.send(JSON.stringify({
 				type: "hello",
@@ -83,18 +163,36 @@ var WebRtcConn = class {
 				token: authToken
 			}));
 		};
-		ws.onerror = (e) => this.rejectReady(/* @__PURE__ */ new Error(`signaling error: ${String(e?.message ?? e)}`));
-		ws.onclose = () => {
-			if (!this.confirmed) this.rejectReady(/* @__PURE__ */ new Error("signaling closed before connect"));
+		ws.onerror = (e) => this.rejectReady(socketError(this.sig, String(e?.message ?? e)));
+		ws.onclose = (ev) => {
+			if (!this.confirmed) this.rejectReady(closeError(this.sig, Number(ev?.code ?? 0), String(ev?.reason ?? "")));
 		};
 		ws.onmessage = (ev) => void this.onSignal(ev);
 		return ws;
 	}
 	async onSignal(ev) {
 		const m = JSON.parse(typeof ev.data === "string" ? ev.data : await ev.data.text());
-		if (m.type === "offer") {
-			this.hostPeer = m.from;
-			const pc = new RTCPeerConnection({ iceServers: m.iceServers || [] });
+		const action = reduceSignal(this.sig, m);
+		if (action.kind === "fail") {
+			this.rejectReady(action.error);
+			return;
+		}
+		if (action.kind === "duplicate-offer") {
+			if (!this.warnedDuplicateHost) {
+				this.warnedDuplicateHost = true;
+				process.stderr.write(`[webrtc] a second host offered in room ${this.link.room} — two hosts serve this room; on the host, stop the stray one (\`ay serve status\`)\n`);
+			}
+			return;
+		}
+		if (action.kind === "candidate") {
+			if (action.queue) this.earlyCandidates.push(action.candidate);
+			else if (this.pc) await this.pc.addIceCandidate(action.candidate).catch(() => {});
+			return;
+		}
+		if (action.kind === "offer") {
+			this.sig.offered = true;
+			this.hostPeer = action.from ?? null;
+			const pc = new RTCPeerConnection({ iceServers: action.iceServers || [] });
 			this.pc = pc;
 			pc.onicecandidate = (e) => {
 				if (e.candidate) this.ws.send(JSON.stringify({
@@ -117,11 +215,14 @@ var WebRtcConn = class {
 			};
 			await pc.setRemoteDescription({
 				type: "offer",
-				sdp: m.sdp
+				sdp: action.sdp
 			});
+			const early = this.earlyCandidates;
+			this.earlyCandidates = [];
+			for (const c of early) await pc.addIceCandidate(c).catch(() => {});
 			const answer = await pc.createAnswer();
 			await pc.setLocalDescription(answer);
-			this.th = await computeTranscriptHash(m.sdp, pc.localDescription.sdp);
+			this.th = await computeTranscriptHash(action.sdp, pc.localDescription.sdp);
 			const keys = await deriveDirKeys(this.link.s, this.th);
 			this.keyC2H = keys.keyC2H;
 			this.keyH2C = keys.keyH2C;
@@ -130,7 +231,7 @@ var WebRtcConn = class {
 				to: this.hostPeer,
 				sdp: pc.localDescription.sdp
 			}));
-		} else if (m.type === "candidate" && this.pc) await this.pc.addIceCandidate(m.candidate).catch(() => {});
+		}
 	}
 	enqueueSeal(flags, obj) {
 		this.sendChain = this.sendChain.then(async () => {
@@ -164,6 +265,7 @@ var WebRtcConn = class {
 			if (env.echo && env.echo === this.myNonce) this.confirmedIn = true;
 			if (this.confirmedIn && this.confirmedOut) {
 				this.confirmed = true;
+				this.sig.confirmed = true;
 				this.resolveReady();
 			}
 			return;
@@ -260,9 +362,8 @@ async function startWebrtcBridge(link) {
 	try {
 		await conn.ready;
 	} catch (e) {
-		const cause = String(e?.message ?? e);
-		const probe = await probeSignalingHost(parsed.host);
-		throw new Error(signalingFailureHint(cause, probe, parsed.host));
+		const err = e instanceof Error ? e : new Error(String(e));
+		throw new Error(await describeConnectFailure(err, parsed.host, async (cause) => signalingFailureHint(cause, await probeSignalingHost(parsed.host), parsed.host)));
 	}
 	const server = Bun.serve({
 		port: 0,
@@ -297,4 +398,4 @@ async function startWebrtcBridge(link) {
 
 //#endregion
 export { startWebrtcBridge };
-//# sourceMappingURL=webrtcRemote-Cd4vTrgv.js.map
+//# sourceMappingURL=webrtcRemote-Cy5kB8aR.js.map

package/dist/{widget-DgBDIGRQ.js → widget-DneXqnL8.js}

@@ -28,7 +28,7 @@ function parseFlags(args, known) {
 }
 /** Resolve the local daemon base URL + token (flags override discovery). */
 async function daemonTarget(flags) {
-	const { resolveDaemonHttpBase, loadTokenReadOnly } = await import("./serve-DVoYVgBo.js");
+	const { resolveDaemonHttpBase, loadTokenReadOnly } = await import("./serve-F5tXYO0-.js");
 	const base = typeof flags.base === "string" ? flags.base : await resolveDaemonHttpBase();
 	if (!base) throw new Error("no running ay serve daemon found — start `ay serve` or pass --base <url> (e.g. http://127.0.0.1:PORT)");
 	const token = typeof flags.token === "string" ? flags.token : await loadTokenReadOnly() ?? "";
@@ -186,7 +186,7 @@ async function cmdMint(args) {
 	const bad = caps.filter((c) => !KNOWN_CAPS.has(c));
 	if (bad.length) throw new Error(`unknown cap(s): ${bad.join(", ")} (valid: ${[...KNOWN_CAPS].join(", ")})`);
 	const ttlSec = parseTtlSec(typeof flags.ttl === "string" ? flags.ttl : "15m");
-	const { mintScopedTermToken } = await import("./serve-DVoYVgBo.js");
+	const { mintScopedTermToken } = await import("./serve-F5tXYO0-.js");
 	const r = await mintScopedTermToken(target, {
 		ttlSec,
 		caps
@@ -202,4 +202,4 @@ async function cmdMint(args) {
 
 //#endregion
 export { cmdMint, cmdWidget };
-//# sourceMappingURL=widget-DgBDIGRQ.js.map
+//# sourceMappingURL=widget-DneXqnL8.js.map

package/dist/{ws-DnBg8-g-.js → ws-DPw1lVTi.js}

@@ -5,10 +5,10 @@ import "./pidStore-DXWqzTSz.js";
 import "./messageLog-Brx3w6zT.js";
 import "./e2e-z1xpwSAg.js";
 import "./configShared-DKTgiz7K.js";
-import "./subcommands-UWLkF5pq.js";
+import "./subcommands-Ddo2TYZs.js";
 import "./notifyStore-2SWKGwZI.js";
 import "./webrtcLink-DFRyWNMs.js";
-import "./remotes-B4v0Nowo.js";
-import { a as isPathInside, c as walkWorkspaces, i as importProvisionModule, l as workspaceStatus, n as cmdWs, o as loadProvision, r as collectWorkspaces, s as resolveOperand, t as WS_JSON_SCHEMA } from "./ws-dc7MP054.js";
+import "./remotes-B4CNXwDS.js";
+import { a as isPathInside, c as walkWorkspaces, i as importProvisionModule, l as workspaceStatus, n as cmdWs, o as loadProvision, r as collectWorkspaces, s as resolveOperand, t as WS_JSON_SCHEMA } from "./ws-Dr-0Ckq7.js";
 
 export { WS_JSON_SCHEMA, cmdWs, collectWorkspaces, isPathInside, loadProvision, walkWorkspaces, workspaceStatus };

package/dist/{ws-dc7MP054.js → ws-Dr-0Ckq7.js}

@@ -1,4 +1,4 @@
-import { V as listRecords } from "./subcommands-UWLkF5pq.js";
+import { V as listRecords } from "./subcommands-Ddo2TYZs.js";
 import { a as getProvisionRoot } from "./workspaceConfig-DTvPtr5j.js";
 import { existsSync } from "fs";
 import { lstat, opendir } from "fs/promises";
@@ -424,4 +424,4 @@ async function cmdWs(args) {
 
 //#endregion
 export { isPathInside as a, walkWorkspaces as c, importProvisionModule as i, workspaceStatus as l, cmdWs as n, loadProvision as o, collectWorkspaces as r, resolveOperand as s, WS_JSON_SCHEMA as t };
-//# sourceMappingURL=ws-dc7MP054.js.map
+//# sourceMappingURL=ws-Dr-0Ckq7.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-yes",
-  "version": "1.300.3",
+  "version": "1.300.4",
   "description": "A wrapper tool that automates interactions with various AI CLI tools by automatically handling common prompts and responses.",
   "keywords": [
     "ai",

package/ts/remoteCache.bun.spec.ts

@@ -0,0 +1,191 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtemp, readdir, readFile, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+import {
+  cacheAgeLabel,
+  hhmm,
+  humanizeAge,
+  isStale,
+  jsonRemote,
+  noteSnapshotResult,
+  parseWaitFor,
+  readRemoteSnapshot,
+  remoteCachePath,
+  writeRemoteSnapshot,
+  type RemoteSnapshot,
+} from "./remoteCache.ts";
+
+const T = 1_800_000_000_000;
+const rows = [{ pid: 1111, cli: "claude", status: "active" }];
+const good: RemoteSnapshot = {
+  version: 1,
+  alias: "alpha",
+  fetchedAt: T,
+  records: rows,
+  error: null,
+};
+
+describe("noteSnapshotResult", () => {
+  it("a success replaces the rows, stamps fetchedAt and clears the error", () => {
+    const prev: RemoteSnapshot = {
+      ...good,
+      fetchedAt: T - 60_000,
+      records: [],
+      error: { message: "x", since: T - 30_000, lastTriedAt: T - 1 },
+    };
+    expect(noteSnapshotResult(prev, "alpha", { ok: true, records: rows }, T)).toEqual(good);
+  });
+
+  it("a failure keeps the last good rows and preserves when the streak began", () => {
+    const first = noteSnapshotResult(good, "alpha", { ok: false, message: "timeout" }, T + 1000);
+    expect(first.records).toBe(rows);
+    expect(first.fetchedAt).toBe(T);
+    expect(first.error).toEqual({ message: "timeout", since: T + 1000, lastTriedAt: T + 1000 });
+    const second = noteSnapshotResult(first, "alpha", { ok: false, message: "refused" }, T + 5000);
+    expect(second.error).toEqual({ message: "refused", since: T + 1000, lastTriedAt: T + 5000 });
+  });
+
+  it("a first-ever failure has no rows and starts the streak now", () => {
+    const s = noteSnapshotResult(null, "beta", { ok: false, message: "dns" }, T);
+    expect(s).toEqual({
+      version: 1,
+      alias: "beta",
+      fetchedAt: null,
+      records: [],
+      error: { message: "dns", since: T, lastTriedAt: T },
+    });
+  });
+});
+
+describe("isStale", () => {
+  it("treats no snapshot, never-fetched, old, and clock-backwards as stale", () => {
+    expect(isStale(null, T)).toBe(true);
+    expect(isStale({ ...good, fetchedAt: null }, T)).toBe(true);
+    expect(isStale(good, T + 30_000)).toBe(true);
+    expect(isStale(good, T - 1)).toBe(true);
+  });
+  it("serves fresh rows as-is", () => {
+    expect(isStale(good, T + 29_999)).toBe(false);
+    expect(isStale(good, T + 5_000, 1_000)).toBe(true);
+  });
+});
+
+describe("labels", () => {
+  it("humanizeAge keeps the table vocabulary", () => {
+    expect(humanizeAge(500)).toBe("0s");
+    expect(humanizeAge(59_000)).toBe("59s");
+    expect(humanizeAge(60_000)).toBe("1m");
+    expect(humanizeAge(3_600_000)).toBe("1h");
+    expect(humanizeAge(2 * 86_400_000)).toBe("2d");
+  });
+
+  it("hhmm is zero-padded local wall-clock", () => {
+    const d = new Date(2026, 0, 1, 9, 5);
+    expect(hhmm(d.getTime())).toBe("09:05");
+  });
+
+  it("cacheAgeLabel says where the rows came from and never hides an outage", () => {
+    expect(cacheAgeLabel(good, T + 180_000, true)).toBe("cached 3m ago, refreshing…");
+    expect(cacheAgeLabel(good, T + 180_000, false)).toBe("cached 3m ago");
+    expect(cacheAgeLabel(null, T, true)).toBe("no cache yet, refreshing…");
+    const since = new Date(2026, 0, 1, 14, 2).getTime();
+    const down: RemoteSnapshot = { ...good, error: { message: "x", since, lastTriedAt: since } };
+    expect(cacheAgeLabel(down, T + 720_000, true)).toBe("cached 12m ago, unreachable since 14:02");
+  });
+});
+
+describe("parseWaitFor", () => {
+  const aliases = ["alpha", "beta"];
+  it("expands all / local, and accepts a comma list of configured aliases", () => {
+    expect(parseWaitFor("all", aliases)).toEqual({ local: true, remotes: ["alpha", "beta"] });
+    expect(parseWaitFor("local", aliases)).toEqual({ local: true, remotes: [] });
+    expect(parseWaitFor("beta", aliases)).toEqual({ local: false, remotes: ["beta"] });
+    expect(parseWaitFor(" alpha, beta ,alpha", aliases)).toEqual({
+      local: false,
+      remotes: ["alpha", "beta"],
+    });
+  });
+  it("refuses an unknown alias or an empty value rather than waiting for nothing", () => {
+    expect(parseWaitFor("gamma", aliases)).toMatchObject({
+      error: expect.stringContaining("gamma"),
+    });
+    expect(parseWaitFor("", aliases)).toMatchObject({
+      error: expect.stringContaining("--waitFor"),
+    });
+    expect(parseWaitFor("x", [])).toMatchObject({ error: expect.stringContaining("none") });
+  });
+});
+
+describe("jsonRemote", () => {
+  it("exposes fetchedAt, stale and age so a parser can decide", () => {
+    expect(jsonRemote(good, T + 1000)).toEqual({
+      fetchedAt: T,
+      stale: false,
+      ageMs: 1000,
+      error: null,
+      records: rows,
+    });
+    expect(jsonRemote(null, T)).toEqual({
+      fetchedAt: null,
+      stale: true,
+      ageMs: null,
+      error: null,
+      records: [],
+    });
+  });
+});
+
+describe("snapshot files", () => {
+  let home: string;
+  const prev = process.env.AGENT_YES_HOME;
+  beforeEach(async () => {
+    home = await mkdtemp(path.join(tmpdir(), "ay-remote-cache-"));
+    process.env.AGENT_YES_HOME = home;
+  });
+  afterEach(async () => {
+    if (prev === undefined) delete process.env.AGENT_YES_HOME;
+    else process.env.AGENT_YES_HOME = prev;
+    await rm(home, { recursive: true, force: true });
+  });
+
+  it("round-trips, encodes an unsafe alias into the file name, and leaves no temp file", async () => {
+    const snap: RemoteSnapshot = { ...good, alias: "a/b c" };
+    await writeRemoteSnapshot(snap);
+    expect(remoteCachePath("a/b c")).toBe(path.join(home, "remotes", "a%2Fb%20c.cache.json"));
+    expect(await readRemoteSnapshot("a/b c")).toEqual(snap);
+    expect(await readdir(path.join(home, "remotes"))).toEqual(["a%2Fb%20c.cache.json"]);
+    expect(JSON.parse(await readFile(remoteCachePath("a/b c"), "utf-8")).version).toBe(1);
+  });
+
+  it("reads a missing, corrupt, or foreign file as a cold cache", async () => {
+    expect(await readRemoteSnapshot("none")).toBeNull();
+    await writeRemoteSnapshot(good);
+    await writeFile(remoteCachePath("alpha"), "{not json");
+    expect(await readRemoteSnapshot("alpha")).toBeNull();
+    await writeFile(remoteCachePath("alpha"), JSON.stringify({ version: 2, records: [] }));
+    expect(await readRemoteSnapshot("alpha")).toBeNull();
+    await writeFile(remoteCachePath("alpha"), JSON.stringify([1, 2]));
+    expect(await readRemoteSnapshot("alpha")).toBeNull();
+  });
+
+  it("tolerates a half-valid error object and a bad fetchedAt", async () => {
+    await writeFile(
+      remoteCachePath("alpha"),
+      JSON.stringify({ version: 1, fetchedAt: "soon", records: rows, error: { message: "x" } }),
+    ).catch(async () => {
+      await writeRemoteSnapshot(good); // ensure the dir exists, then overwrite
+      await writeFile(
+        remoteCachePath("alpha"),
+        JSON.stringify({ version: 1, fetchedAt: "soon", records: rows, error: { message: "x" } }),
+      );
+    });
+    expect(await readRemoteSnapshot("alpha")).toEqual({
+      version: 1,
+      alias: "alpha",
+      fetchedAt: null,
+      records: rows,
+      error: null,
+    });
+  });
+});