agent-yes 1.297.0 → 1.298.0

package/dist/{subcommands-BFcfYykF.js → subcommands-DoKUSvaF.js}

@@ -317,6 +317,140 @@ function toEvent(a, ts) {
 	};
 }
 
+//#endregion
+//#region ts/untilMatch.ts
+/**
+* Compile an `--until` spec into a line predicate.
+*
+* Throws on an empty pattern (a match-everything predicate would return on the
+* agent's next line of output, which is never what the caller meant) and on an
+* invalid regex, so the failure surfaces at argument-parse time rather than as
+* an instant bogus exit 0.
+*/
+function compileUntil(spec) {
+	const { pattern, regex, ignoreCase } = spec;
+	if (pattern.length === 0) throw new Error("--until requires a non-empty pattern");
+	if (!regex) {
+		if (!ignoreCase) return (line) => line.includes(pattern);
+		const needle = pattern.toLowerCase();
+		return (line) => line.toLowerCase().includes(needle);
+	}
+	let re;
+	try {
+		re = new RegExp(pattern, ignoreCase ? "i" : "");
+	} catch (e) {
+		throw new Error(`invalid --until regex: ${e.message}`);
+	}
+	return (line) => re.test(line);
+}
+function makeTally(match, needed = 1) {
+	if (!Number.isInteger(needed) || needed < 1) throw new Error(`--count must be a positive integer (got ${needed})`);
+	let hits = 0;
+	let last = null;
+	const tally = {
+		get hits() {
+			return hits;
+		},
+		needed,
+		get last() {
+			return last;
+		},
+		get done() {
+			return hits >= needed;
+		},
+		feed(line) {
+			if (hits < needed && match(line)) {
+				hits++;
+				last = line;
+			}
+			return hits >= needed;
+		},
+		feedAll(lines) {
+			for (const line of lines) if (tally.feed(line)) return true;
+			return hits >= needed;
+		}
+	};
+	return tally;
+}
+/**
+* The lines strictly after the LAST occurrence of `anchor` — the tail of a log
+* that a follower has not seen yet, given the newest line it had seen.
+*
+* Needed because an exiting agent's log is not the file the follower was reading:
+* the runtime renders the scrollback to a new path and unlinks the raw log, so the
+* final lines must be recovered from a file with unknown overlap. Aligning on the
+* newest already-seen line — from the END, so a repeated shell prompt resolves to
+* the most recent one — bounds that overlap without byte offsets.
+*
+* Returns null when there is no anchor or it isn't present: the caller must then
+* skip the drain rather than fall back to scanning everything, which could report
+* a match printed before the wait even began.
+*/
+function linesAfterAnchor(lines, anchor) {
+	if (anchor === null) return null;
+	const at = lines.lastIndexOf(anchor);
+	if (at < 0) return null;
+	return lines.slice(at + 1);
+}
+function makeJudge(tally, failTally) {
+	let outcome = null;
+	let matched = null;
+	const judge = {
+		get settled() {
+			return outcome !== null;
+		},
+		get outcome() {
+			return outcome;
+		},
+		get matched() {
+			return matched;
+		},
+		test(line) {
+			if (outcome !== null) return true;
+			if (failTally?.feed(line)) {
+				outcome = "failed";
+				matched = failTally.last;
+				return true;
+			}
+			if (tally.feed(line)) {
+				outcome = "match";
+				matched = tally.last;
+				return true;
+			}
+			return false;
+		},
+		testAll(lines) {
+			for (const line of lines) if (judge.test(line)) return true;
+			return outcome !== null;
+		}
+	};
+	return judge;
+}
+/**
+* Exit code for an `--until` run. Mirrors the code family already established by
+* `ay status --wait` / `ay result --wait`, so an orchestrator can branch on the
+* status without parsing stdout:
+*
+*   0  the pattern appeared
+*   1  the agent exited without ever printing it (it's done; it never will)
+*   2  `--timeout` elapsed, or we were signalled away, with no match
+*   3  a `--fail-on` pattern appeared first — the thing went wrong, and waiting
+*      out the timeout would only delay finding out
+*
+* `stopped` (Ctrl-C / SIGTERM, e.g. an outer `timeout(1)`) deliberately shares
+* exit 2 with a timeout rather than the plain-follow 0: for a caller using this
+* as a predicate, "I was killed" must never read as "the pattern matched".
+*/
+function untilExitCode(outcome) {
+	switch (outcome) {
+		case "match": return 0;
+		case "exited": return 1;
+		case "timeout":
+		case "stopped": return 2;
+		case "failed": return 3;
+	}
+}
+
 //#endregion
 //#region ts/resultEnvelope.ts
 /**
@@ -1546,7 +1680,7 @@ async function runSubcommand(argv) {
 		switch (sub) {
 			case "ls":
 			case "list": return await cmdLs(rest);
-			case "ps": return await (await import("./cmdPs-CROJ_bxk.js")).cmdPs(rest);
+			case "ps": return await (await import("./cmdPs-CNue6rFE.js")).cmdPs(rest);
 			case "status": return await cmdStatus(rest);
 			case "whoami": return await cmdWhoami(rest);
 			case "result": return await cmdResult(rest);
@@ -1593,35 +1727,35 @@ async function runSubcommand(argv) {
 				return cmdCh(rest);
 			}
 			case "term": {
-				const { cmdTerm } = await import("./terminal-Cdx9yEVr.js");
+				const { cmdTerm } = await import("./terminal-DOY_IN5y.js");
 				return cmdTerm(rest);
 			}
 			case "widget": {
-				const { cmdWidget } = await import("./widget-a48Lqs0Z.js");
+				const { cmdWidget } = await import("./widget-DKt2rH9F.js");
 				return cmdWidget(rest);
 			}
 			case "mint": {
-				const { cmdMint } = await import("./widget-a48Lqs0Z.js");
+				const { cmdMint } = await import("./widget-DKt2rH9F.js");
 				return cmdMint(rest);
 			}
 			case "serve": {
-				const { cmdServe } = await import("./serve-GoY2ofRT.js");
+				const { cmdServe } = await import("./serve-cvUh5Oab.js");
 				return cmdServe(rest);
 			}
 			case "tray": {
-				const { cmdTray } = await import("./trayApp-Dxs6p7R2.js");
+				const { cmdTray } = await import("./trayApp-DAs4YVeV.js");
 				return cmdTray(rest);
 			}
 			case "setup": {
-				const { cmdSetup } = await import("./setup-DwQ-pEQQ.js");
+				const { cmdSetup } = await import("./setup-Ba2SPIhs.js");
 				return cmdSetup(rest);
 			}
 			case "ws": {
-				const { cmdWs } = await import("./ws-BuLkRFmu.js");
+				const { cmdWs } = await import("./ws-Bs9AVLZR.js");
 				return cmdWs(rest);
 			}
 			case "schedule": {
-				const { cmdSchedule } = await import("./schedule-BZReJzie.js");
+				const { cmdSchedule } = await import("./schedule-2xXpYxCv.js");
 				return cmdSchedule(rest);
 			}
 			case "remote": {
@@ -1633,7 +1767,7 @@ async function runSubcommand(argv) {
 				return cmdExpose(rest);
 			}
 			case "callback": {
-				const { cmdCallback } = await import("./callback-B5gNxIT_.js");
+				const { cmdCallback } = await import("./callback-Blg3DkI3.js");
 				return cmdCallback(rest);
 			}
 			case "reap":
@@ -1644,7 +1778,7 @@ async function runSubcommand(argv) {
 				return await cmdDsh(rest);
 			}
 			case "gc": {
-				const { gcOldBinaryDirs } = await import("./rustBinary-DC-BbqOQ.js");
+				const { gcOldBinaryDirs } = await import("./rustBinary-D59v2mmy.js");
 				const { gcLogs } = await import("./globalPidIndex-DC93JhHQ.js");
 				const bins = gcOldBinaryDirs();
 				const logs = await gcLogs();
@@ -1705,7 +1839,7 @@ async function cmdHelp(managerCommands = true) {
 	const wsLines = managerCommands ? "  ay ws ls [--status]                 list <owner>/<repo>/tree/<branch> workspaces\n  ay ws new <owner>/<repo>[@branch]   clone/refresh a workspace (ay ws help for more)\n" : ``;
 	const self = process.env.AGENT_YES_PID ? await resolveSender() : null;
 	const agentSection = self ? await buildAgentContextSection(self) : "";
-	process.stdout.write(agentSection + "ay - agent-yes CLI\n\nManagement:\n  ay ls [keyword]                     list running agents\n  ay ps [keyword]                     per-agent CPU/RSS, rolled up over each\n                                        agent's whole process tree, + box vitals\n  ay tail [-f] [-n N] <keyword>       last N lines (96), -f to follow\n  ay read <keyword> [page opts]       paginate: --last/--head N, --range A:B,\n                                        --before-line L [--limit N]\n  ay cat <keyword>                    full log\n  ay head <keyword>                   first N lines\n  ay hist [-n 6] [--all] [--json]     past agent conversations (claude/codex\n                                        transcripts, incl. exited sessions);\n                                        this cwd unless --all\n  ay send <keyword> <msg>             send a message (keyword '.' = agent in this cwd)\n  ay msgs [keyword] [--in|--out]      inter-agent message log (sent + received)\n  ay ch mk|join|send|read|tail <topic>  local-first E2E channels: AI ↔ humans on a topic (ay ch help)\n  ay term embed <pid>                 <script> to embed a live read-only agent terminal in a page (ay term help)\n  ay widget ls | read selection|dom   read an opted-in page widget's context (selection/DOM) (ay widget help)\n  ay mint <target> --caps ...         mint a scoped, short-TTL capability token (embeddable in a page)\n  ay key <keyword> <key...>           send raw keystrokes (down/up/enter/esc/…) — drives menus\n  ay select <keyword> <N>             pick option N of a needs_input selection menu\n  ay attach <keyword>                 interactive attach (detach: Ctrl-\\)\n  ay stop <keyword>                   graceful shutdown (/exit for claude/codex)\n  ay exit <keyword> [reason]          graceful shutdown, recording who/why (= 'ay send <kw> exit')\n  ay restart <keyword> [--fresh]      stop (if live) + relaunch resuming the session; --fresh replays the prompt\n  ay status <keyword>                 agent status snapshot\n  ay notify watch --unread            get notified when sub-agents finish/stuck/crash (writes to inbox)\n  ay whoami [--json]                  (inside an agent) your own registry identity + reply address\n  ay result <keyword> [--wait]        pull an agent's structured result envelope\n  ay result set '<json>'              (inside an agent) deposit your result envelope\n  ay reap                             kill process groups leaked by dead agents\n  ay gc                               reclaim old-version binary cache dirs + stale session logs\n  ay dsh-legacy [args...]              launch the DeepSeek Harness terminal client (dsh-tui)\n" + wsLines + "\nRemote:\n" + setupLine + "  ay schedule <when> <cli> -- <msg>   run an agent on a schedule (HH:MM or cron)\n  ay serve [--port N]                 start HTTP API server (prints token)\n  ay serve status                     show serve daemon/server status\n  ay remote add <alias> http://<token>@<host>:<port>\n  ay remote ls / rm <alias>           manage saved remotes\n  ay expose <port>                    share localhost:<port> at https://<id>.agent-yes.com (private link)\n  ay callback --expires 7d           mint an embeddable message-me widget for one agent\n  ay ls   <token>@<host>:<port>       connect inline (no alias needed)\n  ay send <token>@<host>:<port>:<kw> <msg>\n\nRun an agent (naming a CLI is what launches one — bare 'ay' shows this help):\n  ay <claude|codex|...> [options] -- [prompt]\n  ay claude -- \"fix the bug in auth.ts\"\n  cy [options] -- [prompt]            shortcut for 'ay claude' (bare 'cy' starts claude)\n  ay claude --help                    full agent-runner options\n\nLabs (examples at https://github.com/snomiao/agent-yes/tree/main/lab):\n  local-role-play/   designer + builder on one machine\n  http-remote/       ay serve remote access demo\n  p2p-pairing/       libp2p P2P  (needs: cargo build --features swarm)\n");
+	process.stdout.write(agentSection + "ay - agent-yes CLI\n\nManagement:\n  ay ls [keyword]                     list running agents\n  ay ps [keyword]                     per-agent CPU/RSS, rolled up over each\n                                        agent's whole process tree, + box vitals\n  ay tail [-f] [-n N] <keyword>       last N lines (96), -f to follow\n  ay tail <keyword> --until TEXT      block until TEXT is printed, then exit 0\n      [--timeout 10m] [-q] [--regex]    (1 = agent exited without it, 2 = no match,\n      [--fail-on TEXT] [--count N]       3 = --fail-on hit first)\n  ay read <keyword> [page opts]       paginate: --last/--head N, --range A:B,\n                                        --before-line L [--limit N]\n  ay cat <keyword>                    full log\n  ay head <keyword>                   first N lines\n  ay hist [-n 6] [--all] [--json]     past agent conversations (claude/codex\n                                        transcripts, incl. exited sessions);\n                                        this cwd unless --all\n  ay send <keyword> <msg>             send a message (keyword '.' = agent in this cwd)\n  ay msgs [keyword] [--in|--out]      inter-agent message log (sent + received)\n  ay ch mk|join|send|read|tail <topic>  local-first E2E channels: AI ↔ humans on a topic (ay ch help)\n  ay term embed <pid>                 <script> to embed a live read-only agent terminal in a page (ay term help)\n  ay widget ls | read selection|dom   read an opted-in page widget's context (selection/DOM) (ay widget help)\n  ay mint <target> --caps ...         mint a scoped, short-TTL capability token (embeddable in a page)\n  ay key <keyword> <key...>           send raw keystrokes (down/up/enter/esc/…) — drives menus\n  ay select <keyword> <N>             pick option N of a needs_input selection menu\n  ay attach <keyword>                 interactive attach (detach: Ctrl-\\)\n  ay stop <keyword>                   graceful shutdown (/exit for claude/codex)\n  ay exit <keyword> [reason]          graceful shutdown, recording who/why (= 'ay send <kw> exit')\n  ay restart <keyword> [--fresh]      stop (if live) + relaunch resuming the session; --fresh replays the prompt\n  ay status <keyword>                 agent status snapshot\n  ay notify watch --unread            get notified when sub-agents finish/stuck/crash (writes to inbox)\n  ay whoami [--json]                  (inside an agent) your own registry identity + reply address\n  ay result <keyword> [--wait]        pull an agent's structured result envelope\n  ay result set '<json>'              (inside an agent) deposit your result envelope\n  ay reap                             kill process groups leaked by dead agents\n  ay gc                               reclaim old-version binary cache dirs + stale session logs\n  ay dsh-legacy [args...]              launch the DeepSeek Harness terminal client (dsh-tui)\n" + wsLines + "\nRemote:\n" + setupLine + "  ay schedule <when> <cli> -- <msg>   run an agent on a schedule (HH:MM or cron)\n  ay serve [--port N]                 start HTTP API server (prints token)\n  ay serve status                     show serve daemon/server status\n  ay remote add <alias> http://<token>@<host>:<port>\n  ay remote ls / rm <alias>           manage saved remotes\n  ay expose <port>                    share localhost:<port> at https://<id>.agent-yes.com (private link)\n  ay callback --expires 7d           mint an embeddable message-me widget for one agent\n  ay ls   <token>@<host>:<port>       connect inline (no alias needed)\n  ay send <token>@<host>:<port>:<kw> <msg>\n\nRun an agent (naming a CLI is what launches one — bare 'ay' shows this help):\n  ay <claude|codex|...> [options] -- [prompt]\n  ay claude -- \"fix the bug in auth.ts\"\n  cy [options] -- [prompt]            shortcut for 'ay claude' (bare 'cy' starts claude)\n  ay claude --help                    full agent-runner options\n\nLabs (examples at https://github.com/snomiao/agent-yes/tree/main/lab):\n  local-role-play/   designer + builder on one machine\n  http-remote/       ay serve remote access demo\n  p2p-pairing/       libp2p P2P  (needs: cargo build --features swarm)\n");
 	return 0;
 }
 function matchKeyword(record, keyword) {
@@ -1895,7 +2029,7 @@ async function runRemoteLs(remote, opts) {
 	}
 	return 0;
 }
-async function runRemoteRead(remote, mode, follow, n, reconnectTimeoutMs = 12e4, _plain = false) {
+async function runRemoteRead(remote, mode, follow, n, reconnectTimeoutMs = 12e4, _plain = false, until) {
 	const keyword = remote.keyword ?? "";
 	if (!keyword) {
 		process.stderr.write("remote tail/cat/head requires a keyword (e.g. token@host:port:keyword)\n");
@@ -1903,12 +2037,67 @@ async function runRemoteRead(remote, mode, follow, n, reconnectTimeoutMs = 12e4,
 	}
 	if (mode === "tail" && follow) {
 		const ac = new AbortController();
+		const judge = until ? makeJudge(until.tally, until.failTally) : null;
+		let outcome = "stopped";
+		const settle = (o) => {
+			outcome = o;
+			ac.abort();
+		};
+		const untilTimer = until && until.timeoutMs !== null ? setTimeout(() => settle("timeout"), until.timeoutMs) : null;
+		let remoteDeadSince = null;
+		let sawRemoteLive = false;
+		const statusPoll = until ? setInterval(() => {
+			(async () => {
+				const liveness = await remoteAgentLiveness(remote, keyword);
+				if (liveness === null) return;
+				if (liveness === "live") {
+					sawRemoteLive = true;
+					remoteDeadSince = null;
+					return;
+				}
+				if (!sawRemoteLive) return;
+				if (remoteDeadSince === null) {
+					remoteDeadSince = Date.now();
+					return;
+				}
+				if (!judge?.settled) settle("exited");
+			})();
+		}, UNTIL_REMOTE_STATUS_POLL_MS) : null;
+		statusPoll?.unref?.();
+		/** Reassembles frames into lines; `flush` tests a trailing partial at the end. */
+		let lineBuf = "";
+		const consume = (text, test) => {
+			if (!until?.quiet) {
+				process.stdout.write(text);
+				if (!text.endsWith("\n")) process.stdout.write("\n");
+			}
+			if (!judge) return;
+			lineBuf += text;
+			const lines = lineBuf.split("\n");
+			lineBuf = lines.pop() ?? "";
+			if (!test) return;
+			if (judge.testAll(lines.map((l) => l.trimEnd()))) settle(judge.outcome ?? "match");
+		};
+		const flushLineBuf = () => {
+			if (!judge || lineBuf.length === 0) return;
+			const last = lineBuf.trimEnd();
+			lineBuf = "";
+			if (last && judge.test(last)) settle(judge.outcome ?? "match");
+		};
+		const finishUntil = () => {
+			if (untilTimer) clearTimeout(untilTimer);
+			if (statusPoll) clearInterval(statusPoll);
+			return reportUntil(outcome, judge?.matched ?? null, until.quiet, until.failPattern, {
+				hits: until.tally.hits,
+				needed: until.tally.needed
+			});
+		};
 		const disposeSignals = installStreamSignals(() => ac.abort());
 		ac.signal.addEventListener("abort", disposeSignals, { once: true });
 		const deadline = Date.now() + reconnectTimeoutMs;
 		let delay = 1e3;
 		let attempt = 0;
-		process.stderr.write(`[remote ${remote.label}  ${keyword}]\nfollowing... (Ctrl-C to stop, timeout: ${Math.round(reconnectTimeoutMs / 1e3)}s)\n`);
+		process.stderr.write(until ? `[remote ${remote.label}  ${keyword}]\n${untilBanner(until)}` : `[remote ${remote.label}  ${keyword}]\nfollowing... (Ctrl-C to stop, timeout: ${Math.round(reconnectTimeoutMs / 1e3)}s)\n`);
 		while (!ac.signal.aborted) try {
 			const res = await fetch(`${remote.url}/api/tail/${encodeURIComponent(keyword)}`, {
 				headers: {
@@ -1924,12 +2113,16 @@ async function runRemoteRead(remote, mode, follow, n, reconnectTimeoutMs = 12e4,
 				}
 				throw new Error(`HTTP ${res.status}`);
 			}
-			if (attempt > 0) process.stderr.write("remote: reconnected\n");
+			if (attempt > 0) {
+				process.stderr.write("remote: reconnected\n");
+				if (until) process.stderr.write("remote: output during the gap was not tested for --until\n");
+			}
 			delay = 1e3;
 			const reader = res.body.getReader();
 			const dec = new TextDecoder();
 			let buf = "";
-			while (true) {
+			let firstFrame = true;
+			while (!ac.signal.aborted) {
 				const { done, value } = await reader.read();
 				if (done) break;
 				buf += dec.decode(value, { stream: true });
@@ -1939,16 +2132,39 @@ async function runRemoteRead(remote, mode, follow, n, reconnectTimeoutMs = 12e4,
 					if (!line.startsWith("data: ")) continue;
 					try {
 						const text = JSON.parse(line.slice(6));
-						process.stdout.write(text);
-						if (!text.endsWith("\n")) process.stdout.write("\n");
+						const isContext = firstFrame;
+						firstFrame = false;
+						consume(text, !isContext || Boolean(until?.matchBacklog));
+						if (ac.signal.aborted) break;
 					} catch {}
 				}
+				if (ac.signal.aborted) break;
+			}
+			if (until) {
+				if (judge?.settled) return finishUntil();
+				if (ac.signal.aborted) {
+					flushLineBuf();
+					return finishUntil();
+				}
+				flushLineBuf();
+				if (!judge?.settled) outcome = "exited";
+				return finishUntil();
 			}
 			break;
 		} catch (e) {
-			if (e.name === "AbortError" || ac.signal.aborted) return 0;
+			if (e.name === "AbortError" || ac.signal.aborted) {
+				if (until) {
+					flushLineBuf();
+					return finishUntil();
+				}
+				return 0;
+			}
 			if (Date.now() >= deadline) {
 				process.stderr.write(`remote: timeout after ${Math.round(reconnectTimeoutMs / 1e3)}s, giving up\n`);
+				if (until) {
+					outcome = "timeout";
+					return finishUntil();
+				}
 				return 1;
 			}
 			process.stderr.write(`remote: disconnected (${e.message}), retrying in ${delay / 1e3}s…\n`);
@@ -1959,10 +2175,20 @@ async function runRemoteRead(remote, mode, follow, n, reconnectTimeoutMs = 12e4,
 					reject(/* @__PURE__ */ new Error("abort"));
 				});
 			}).catch(() => {});
-			if (ac.signal.aborted) return 0;
+			if (ac.signal.aborted) {
+				if (until) {
+					flushLineBuf();
+					return finishUntil();
+				}
+				return 0;
+			}
 			delay = Math.min(delay * 2, 3e4);
 			attempt++;
 		}
+		if (until) {
+			flushLineBuf();
+			return finishUntil();
+		}
 		return 0;
 	}
 	const params = new URLSearchParams({
@@ -2778,12 +3004,54 @@ function truncate(s, n) {
 	if (s.length <= n) return s;
 	return s.slice(0, n - 1) + "…";
 }
+/**
+* Parse a human duration (`30s`, `10m`) to ms, or null when it isn't one.
+*
+* `ms()`'s parse overload is typed to a template-literal `StringValue`, which a
+* CLI flag (a plain `string`) never satisfies, and it returns `undefined` — not a
+* number — for unparseable input. Both are handled here once so the call sites
+* just branch on null.
+*/
+function parseDurationMs(value) {
+	const parsed = ms(value);
+	return typeof parsed === "number" && Number.isFinite(parsed) ? parsed : null;
+}
 async function cmdRead(rest, { mode }) {
-	const argv = await yargs(rest).usage("Usage: ay read/cat/tail/head <keyword> [options]\n\nPagination (static read; render the log once, window the rendered lines):\n  --last N | --head N         last / first N lines\n  --range A:B                 lines A..B (1-indexed, inclusive)\n  --before-line L [--limit N] the page of N lines ending just above line L").option("follow", {
+	const argv = await yargs(rest).usage("Usage: ay read/cat/tail/head <keyword> [options]\n\nPagination (static read; render the log once, window the rendered lines):\n  --last N | --head N         last / first N lines\n  --range A:B                 lines A..B (1-indexed, inclusive)\n  --before-line L [--limit N] the page of N lines ending just above line L\n\nWait for output (follow with a predicate; exit 0 matched / 1 exited /\n2 no match / 3 --fail-on hit):\n  --until TEXT [--timeout 10m]   return as soon as TEXT is printed\n  --fail-on TEXT                 give up early (exit 3) if TEXT shows up first\n  --count N                      require N hits of --until (default 1)\n  --regex | -i | -q              regex / case-insensitive / only print the match").option("follow", {
 		alias: "f",
 		type: "boolean",
 		default: false,
 		description: "Follow log output (Ctrl-C to stop)"
+	}).option("until", {
+		type: "string",
+		description: "Follow until this text appears in the output, then exit. Implies -f. Exit 0 matched, 1 agent exited without it, 2 --timeout/interrupted, 3 --fail-on hit first. Literal substring by default; matches only output arriving from now on."
+	}).option("fail-on", {
+		type: "string",
+		description: "Give up with exit 3 if this text appears before --until does (e.g. --until 'all tests passed' --fail-on 'FAILED')"
+	}).option("count", {
+		type: "number",
+		description: "Require this many --until hits before returning (default 1)"
+	}).option("regex", {
+		type: "boolean",
+		default: false,
+		description: "Treat --until as a regular expression"
+	}).option("ignore-case", {
+		alias: "i",
+		type: "boolean",
+		default: false,
+		description: "Case-insensitive --until match"
+	}).option("timeout", {
+		type: "string",
+		description: "Give up waiting for --until after this long (e.g. 30s, 10m)"
+	}).option("match-backlog", {
+		type: "boolean",
+		default: false,
+		description: "Also test the context window printed before following. Off by default: a hit from a PREVIOUS run would return instantly and wrongly."
+	}).option("quiet", {
+		alias: "q",
+		type: "boolean",
+		default: false,
+		description: "With --until, print only the matching line (no streamed output)"
 	}).option("n", {
 		type: "number",
 		description: "Number of lines (default: 96 for tail/head)"
@@ -2823,7 +3091,35 @@ async function cmdRead(rest, { mode }) {
 		description: "Seconds before giving up reconnecting remote SSE (default: 120)"
 	}).help(false).version(false).exitProcess(false).parseAsync();
 	ensureEpipeExit();
-	const plain = Boolean(argv.plain) || !process.stdout.isTTY;
+	const until = typeof argv.until === "string" ? argv.until : null;
+	const plain = Boolean(argv.plain) || until !== null || !process.stdout.isTTY;
+	const failOn = typeof argv["fail-on"] === "string" ? argv["fail-on"] : null;
+	const untilOnlyFlags = [
+		["--regex", argv.regex],
+		["--ignore-case", argv["ignore-case"]],
+		["--match-backlog", argv["match-backlog"]],
+		["--timeout", typeof argv.timeout === "string" && argv.timeout.length > 0],
+		["--fail-on", failOn !== null],
+		["--count", argv.count !== void 0]
+	];
+	if (until === null) {
+		const stray = untilOnlyFlags.find(([, set]) => set);
+		if (stray) throw new Error(`${stray[0]} requires --until <pattern>`);
+	}
+	const compileSpec = (pattern) => compileUntil({
+		pattern,
+		regex: argv.regex,
+		ignoreCase: argv["ignore-case"]
+	});
+	const untilCount = argv.count === void 0 ? 1 : Number(argv.count);
+	if (until !== null && (!Number.isInteger(untilCount) || untilCount < 1)) throw new Error(`--count must be a positive integer (got ${argv.count})`);
+	const untilMatch = until !== null ? compileSpec(until) : null;
+	const failMatch = failOn !== null ? compileSpec(failOn) : null;
+	let untilTimeoutMs = null;
+	if (typeof argv.timeout === "string" && argv.timeout.length > 0) {
+		untilTimeoutMs = parseDurationMs(argv.timeout);
+		if (untilTimeoutMs === null) throw new Error(`invalid --timeout value: ${argv.timeout}`);
+	}
 	const opts = {
 		all: argv.all,
 		active: false,
@@ -2837,9 +3133,20 @@ async function cmdRead(rest, { mode }) {
 		const nFlag2 = argv.n;
 		const n2 = nFlag2 !== void 0 && Number.isFinite(nFlag2) && nFlag2 > 0 ? Math.floor(nFlag2) : mode === "cat" ? 0 : 96;
 		const reconnectTimeoutMs = (argv["reconnect-timeout"] ?? 120) * 1e3;
-		if (remote) return runRemoteRead(remote, mode, argv.follow, n2, reconnectTimeoutMs, plain);
+		if (remote) {
+			if (untilMatch === null) return runRemoteRead(remote, mode, argv.follow, n2, reconnectTimeoutMs, plain);
+			return runRemoteRead(remote, mode, true, n2, reconnectTimeoutMs, plain, {
+				tally: makeTally(untilMatch, untilCount),
+				failTally: failMatch ? makeTally(failMatch, 1) : null,
+				pattern: until,
+				failPattern: failOn,
+				quiet: Boolean(argv.quiet),
+				timeoutMs: untilTimeoutMs,
+				matchBacklog: Boolean(argv["match-backlog"])
+			});
+		}
 	}
-	const follow = argv.follow;
+	const follow = argv.follow || until !== null;
 	const nFlag = argv.n;
 	const n = nFlag !== void 0 && Number.isFinite(nFlag) && nFlag > 0 ? Math.floor(nFlag) : mode === "cat" ? 0 : 96;
 	const record = await resolveOne(keyword, opts);
@@ -2866,10 +3173,31 @@ async function cmdRead(rest, { mode }) {
 			rows: size?.rows
 		});
 		process.stderr.write(header + "\n");
-		process.stdout.write(rendered);
-		if (!rendered.endsWith("\n")) process.stdout.write("\n");
+		if (!(untilMatch && argv.quiet)) {
+			process.stdout.write(rendered);
+			if (!rendered.endsWith("\n")) process.stdout.write("\n");
+		}
+		const tally = untilMatch ? makeTally(untilMatch, untilCount) : null;
+		const failTally = failMatch ? makeTally(failMatch, 1) : null;
+		if (tally && argv["match-backlog"]) {
+			const lines = rendered.split("\n");
+			if (failTally?.feedAll(lines)) return reportUntil("failed", failTally.last, Boolean(argv.quiet), failOn);
+			if (tally.feedAll(lines)) return reportUntil("match", tally.last, Boolean(argv.quiet));
+		}
 		setInterval(() => void recordRead(reader.key, record.pid), 3e4).unref?.();
-		return plain ? followPlainLocal(logPath, buf, stats.size) : followRawLocal(logPath, buf, stats.size);
+		return plain ? followPlainLocal(logPath, buf, stats.size, tally ? {
+			tally,
+			failTally,
+			pattern: until,
+			failPattern: failOn,
+			quiet: Boolean(argv.quiet),
+			timeoutMs: untilTimeoutMs,
+			matchBacklog: Boolean(argv["match-backlog"]),
+			pid: record.pid
+		} : void 0, {
+			cols: size?.cols,
+			rows: size?.rows
+		}) : followRawLocal(logPath, buf, stats.size);
 	}
 	const allLines = await renderRawLogLines(buf, {
 		cols: size?.cols,
@@ -2936,9 +3264,12 @@ function installStreamSignals(stop) {
 * Coalescing file watcher: re-reads `logPath` on every change, hands each newly
 * appended byte range to `onChunk`, and never overlaps reads (a change that
 * arrives mid-read is serviced once the current read finishes). `startOffset`
-* is where the already-emitted prefix ends. Resolves when `stop` is signalled.
+* is where the already-emitted prefix ends. Resolves when `stop` is signalled,
+* or when `signal` aborts (how `--until` stops itself on a match / timeout /
+* the agent's death), and returns the byte offset it stopped at — so a caller
+* can drain whatever landed after the last watch event.
 */
-async function watchAppend(logPath, startOffset, onChunk, onStop) {
+async function watchAppend(logPath, startOffset, onChunk, onStop, signal) {
 	const { watch } = await import("fs");
 	let offset = startOffset;
 	let reading = false;
@@ -2952,12 +3283,15 @@ async function watchAppend(logPath, startOffset, onChunk, onStop) {
 				watcher.close();
 			} catch {}
 			dispose();
+			signal?.removeEventListener("abort", finish);
 			onStop();
 			resolve();
 		};
 		const dispose = installStreamSignals(finish);
+		if (signal) if (signal.aborted) queueMicrotask(finish);
+		else signal.addEventListener("abort", finish);
 		const pump = async () => {
-			if (reading) {
+			if (reading || done) {
 				pending = true;
 				return;
 			}
@@ -2970,6 +3304,7 @@ async function watchAppend(logPath, startOffset, onChunk, onStop) {
 				} catch {
 					break;
 				}
+				if (done) break;
 				if (full.length > offset) {
 					const chunk = full.slice(offset);
 					offset = full.length;
@@ -2981,6 +3316,7 @@ async function watchAppend(logPath, startOffset, onChunk, onStop) {
 		const watcher = watch(logPath, () => void pump());
 		pump();
 	});
+	return offset;
 }
 /**
 * Default (interactive) follow: append each new byte range with ANSI/control
@@ -2997,6 +3333,22 @@ async function followRawLocal(logPath, buf, startOffset = buf.length) {
 	}, () => {});
 	return 0;
 }
+/**
+* `@xterm/headless`'s Terminal constructor, across runtimes.
+*
+* The package is CJS, so `await import()` resolves to `{ default: { Terminal } }`
+* under node while bun hoists the named exports — a plain
+* `const { Terminal } = await import(…)` is therefore `undefined` on node and
+* every render throws "Terminal is not a constructor". That is the runtime npm
+* users get from `dist/`, where it silently degraded the static render to the
+* ANSI-strip fallback and broke `ay tail -f` into a pipe outright.
+*/
+async function loadXtermTerminal() {
+	const mod = await import("@xterm/headless");
+	const Terminal = mod.Terminal ?? mod.default?.Terminal;
+	if (!Terminal) throw new Error("@xterm/headless: no Terminal export");
+	return Terminal;
+}
 /** Absolute index (scrollback + viewport row) of the row the cursor sits on. */
 function cursorAbs(term) {
 	return term.buffer.active.baseY + term.buffer.active.cursorY;
@@ -3025,12 +3377,11 @@ function finalizedLines(term, fromAbs) {
 * settled, so the output is clean, newline-terminated, line-buffered text a
 * script can read. On stop, flush the line the cursor is still sitting on.
 */
-async function followPlainLocal(logPath, buf, startOffset = buf.length) {
-	process.stderr.write(`following... (plain; Ctrl-C / SIGTERM to stop)\n`);
-	const { Terminal } = await import("@xterm/headless");
-	const term = new Terminal({
-		cols: 200,
-		rows: 50,
+async function followPlainLocal(logPath, buf, startOffset = buf.length, until, geom) {
+	process.stderr.write(until ? untilBanner(until) : `following... (plain; Ctrl-C / SIGTERM to stop)\n`);
+	const term = new (await (loadXtermTerminal()))({
+		cols: geom?.cols ?? 200,
+		rows: geom?.rows ?? 50,
 		scrollback: 5e4,
 		allowProposedApi: true
 	});
@@ -3041,19 +3392,197 @@ async function followPlainLocal(logPath, buf, startOffset = buf.length) {
 	};
 	await feed(buf);
 	let emitted = cursorAbs(term);
+	let anchor = null;
+	for (let i = emitted; i >= Math.max(0, emitted - ANCHOR_LOOKBACK_ROWS); i--) {
+		const line = lineAt(i);
+		if (line) {
+			anchor = line;
+			break;
+		}
+	}
+	const ac = new AbortController();
+	let outcome = "stopped";
+	const judge = until ? makeJudge(until.tally, until.failTally) : null;
+	const settled = () => judge?.settled === true;
+	const testLine = (line) => {
+		if (judge && !judge.settled && judge.test(line)) {
+			outcome = judge.outcome ?? "match";
+			ac.abort();
+		}
+	};
 	const flushCommitted = () => {
-		for (const line of finalizedLines(term, emitted)) process.stdout.write(line + "\n");
+		for (const line of finalizedLines(term, emitted)) {
+			if (!until?.quiet) process.stdout.write(line + "\n");
+			if (!until) continue;
+			if (line) anchor = line;
+			testLine(line);
+		}
 		emitted = cursorAbs(term);
 	};
-	await watchAppend(logPath, startOffset, async (chunk) => {
+	const timer = until && until.timeoutMs !== null ? setTimeout(() => {
+		outcome = "timeout";
+		ac.abort();
+	}, until.timeoutMs) : null;
+	let deadSince = null;
+	const liveness = until ? setInterval(() => {
+		if (isPidAlive(until.pid)) {
+			deadSince = null;
+			return;
+		}
+		if (deadSince === null) {
+			deadSince = Date.now();
+			return;
+		}
+		outcome = "exited";
+		ac.abort();
+	}, UNTIL_LIVENESS_POLL_MS) : null;
+	liveness?.unref?.();
+	/**
+	* Emit the cursor's own row — the line still being written — so the last
+	* partial line isn't lost when we stop mid-stream, and so a pattern printed
+	* without a trailing newline still counts (it IS on screen). Self-guarded to
+	* run at most once: a row printed here may finalize later, and emitting it
+	* again would duplicate the agent's last line of output.
+	*/
+	let partialFlushed = false;
+	const flushPartial = () => {
+		if (partialFlushed) return;
+		partialFlushed = true;
+		const last = lineAt(cursorAbs(term));
+		if (!last) return;
+		if (!until?.quiet) process.stdout.write(last + "\n");
+		if (!until) return;
+		anchor = last;
+		testLine(last);
+	};
+	const stoppedAt = await watchAppend(logPath, startOffset, async (chunk) => {
 		await feed(chunk);
 		flushCommitted();
-	}, () => {
-		flushCommitted();
-		const last = lineAt(cursorAbs(term));
-		if (last) process.stdout.write(last + "\n");
+	}, flushCommitted, until ? ac.signal : void 0);
+	if (timer) clearTimeout(timer);
+	if (liveness) clearInterval(liveness);
+	if (!until) {
+		flushPartial();
+		return 0;
+	}
+	if (!settled()) {
+		const tailBytes = await readFile(logPath).catch(() => null);
+		if (tailBytes === null) {
+			flushPartial();
+			await drainFinalLog(until.pid, logPath, anchor, until, testLine);
+		} else if (tailBytes.length > stoppedAt) {
+			await feed(tailBytes.slice(stoppedAt));
+			flushCommitted();
+		}
+	}
+	flushPartial();
+	return reportUntil(outcome, judge?.matched ?? null, until.quiet, until.failPattern, {
+		hits: until.tally.hits,
+		needed: until.tally.needed
 	});
-	return 0;
+}
+/** Cadence of the `--until` liveness poll; two ticks are needed to call it dead. */
+const UNTIL_LIVENESS_POLL_MS = 500;
+/**
+* Cadence of the REMOTE liveness poll; two ticks are needed to call it dead.
+* Slower than the local one because each tick is an HTTP round trip, and the
+* stream itself — not this poll — is what a wait normally ends on.
+*/
+const UNTIL_REMOTE_STATUS_POLL_MS = 2e3;
+/**
+* Whether a remote agent is still running: "live", "gone" (the host answered and
+* the agent is exited or no longer listed), or null when the poll itself failed.
+*
+* Asks `/api/ls`, not `/api/status/<kw>`: only the TS server serves the latter,
+* while the Rust server — the default `ay serve` — has no such route and 404s
+* every poll, so a status-based probe silently never fires.
+*
+* Null is deliberately distinct from "gone": a dropped packet or a restarting
+* host would otherwise end a wait with "the agent exited", the one verdict a
+* caller acts on by giving up and reporting the work unfinished.
+*/
+async function remoteAgentLiveness(remote, keyword) {
+	const params = new URLSearchParams({
+		keyword,
+		all: "1"
+	});
+	try {
+		const res = await remoteGet(remote, `/api/ls?${params}`);
+		if (!res.ok) return null;
+		const records = await res.json();
+		if (!Array.isArray(records)) return null;
+		if (records.length === 0) return "gone";
+		return records.every((r) => r.status === "exited") ? "gone" : "live";
+	} catch {
+		return null;
+	}
+}
+/** How far back from the live frontier to look for a non-empty anchor line. */
+const ANCHOR_LOOKBACK_ROWS = 200;
+/**
+* Last-chance `--until` match against the log an exited agent left behind.
+*
+* On a clean exit the raw byte log we were following is replaced by a rendered
+* scrollback dump at a NEW path, and the pid index is repointed at it. A pattern
+* printed in the agent's last breath can therefore be missing from everything we
+* saw yet present in that file — so re-resolve the path from the registry and
+* scan it.
+*
+* Only the lines AFTER `anchor` (the newest line we had already seen, matched
+* from the END of the file) are tested, so the no-backlog-matching promise
+* survives: a hit from before this command started cannot be reported. When the
+* anchor can't be located the drain is skipped rather than guessed at — a missed
+* match surfaces as a loud exit 1, a false one as a silent wrong answer.
+*
+* Feeds those lines to `testLine`, which owns the verdict — so a `--count` wait
+* finishes on hits split across the stream and this drain, and `--fail-on` still
+* wins over `--until` on the agent's last line.
+*/
+async function drainFinalLog(pid, followedPath, anchor, until, testLine) {
+	if (anchor === null) return;
+	const advertised = (await readGlobalPids()).find((r) => r.pid === pid)?.log_file;
+	const derived = followedPath.endsWith(".raw.log") ? followedPath.slice(0, -8) + ".log" : null;
+	const finalPath = advertised && advertised !== followedPath ? advertised : derived;
+	if (!finalPath) return;
+	const text = await readFile(finalPath, "utf8").catch(() => null);
+	if (text === null) return;
+	const fresh = linesAfterAnchor(text.split("\n").map((l) => l.trimEnd()), anchor);
+	if (fresh === null) return;
+	for (const line of fresh) {
+		if (!until.quiet) process.stdout.write(line + "\n");
+		testLine(line);
+	}
+}
+/** The "waiting for X | fail on Y | timeout Ns…" banner shared by both followers. */
+function untilBanner(wait) {
+	const parts = [`waiting for ${JSON.stringify(wait.pattern)}`];
+	if (wait.tally.needed > 1) parts.push(`x${wait.tally.needed}`);
+	if (wait.tally.hits > 0) parts.push(`(${wait.tally.hits} already seen)`);
+	if (wait.failPattern !== null) parts.push(`| fail on ${JSON.stringify(wait.failPattern)}`);
+	if (wait.timeoutMs !== null) parts.push(`| timeout ${Math.round(wait.timeoutMs / 1e3)}s`);
+	return `${parts.join(" ")}… (Ctrl-C / SIGTERM to stop)\n`;
+}
+/**
+* Report an `--until` result and return its exit code. In quiet mode the matching
+* line is the whole of stdout (a caller can capture it); the human-readable
+* verdict always goes to stderr so it never contaminates that.
+*
+* `progress` (hits/needed) is named on the failure paths only when `--count` asked
+* for more than one: "timed out with 2/3 matches" is the difference between a wait
+* that was close and one that never started.
+*/
+function reportUntil(outcome, matched, quiet, failPattern, progress) {
+	const short = progress && progress.needed > 1 ? ` (${progress.hits}/${progress.needed} matches)` : "";
+	if (outcome === "match" && matched !== null) {
+		if (quiet) process.stdout.write(matched + "\n");
+		process.stderr.write(`[until] matched: ${matched}\n`);
+	} else if (outcome === "failed") {
+		if (quiet && matched !== null) process.stdout.write(matched + "\n");
+		process.stderr.write(`[until] --fail-on ${JSON.stringify(failPattern ?? "")} hit first: ${matched ?? ""}\n`);
+	} else if (outcome === "exited") process.stderr.write(`[until] agent exited without printing it${short}\n`);
+	else if (outcome === "timeout") process.stderr.write(`[until] timed out with no match${short}\n`);
+	else process.stderr.write(`[until] stopped before a match${short}\n`);
+	return untilExitCode(outcome);
 }
 /**
 * Read an agent's last-known PTY geometry from `~/.agent-yes/ptysize/<pid>`
@@ -3152,8 +3681,7 @@ async function renderRawLogLines(buf, geom) {
 	const rows = geom?.rows && geom.rows > 0 ? geom.rows : 50;
 	const scrollback = 5e4;
 	try {
-		const { Terminal } = await import("@xterm/headless");
-		const term = new Terminal({
+		const term = new (await (loadXtermTerminal()))({
 			cols,
 			rows,
 			scrollback,
@@ -4351,7 +4879,7 @@ async function cmdAttach(rest) {
 	const winsizeDir = path.join(ayHome, "winsize");
 	await mkdir(winsizeDir, { recursive: true });
 	const winsizePath = path.join(winsizeDir, String(record.pid));
-	const { resolveDaemonHttpBase, loadTokenReadOnly } = await import("./serve-GoY2ofRT.js");
+	const { resolveDaemonHttpBase, loadTokenReadOnly } = await import("./serve-cvUh5Oab.js");
 	const daemonBase = await resolveDaemonHttpBase().catch(() => null);
 	const daemonToken = daemonBase ? await loadTokenReadOnly().catch(() => null) ?? "" : "";
 	const capViewer = `attach:${process.pid}`;
@@ -5078,7 +5606,7 @@ async function cmdNotify(rest) {
 	}
 	const ensure = async () => {
 		if (!argv["ensure-daemon"]) return;
-		const { ensureDaemon } = await import("./notifyDaemon-849g16zO.js");
+		const { ensureDaemon } = await import("./notifyDaemon-BPpVmmj0.js");
 		await ensureDaemon().catch(() => null);
 	};
 	await heartbeatWatcher(parent, selfStartedAt);
@@ -5152,7 +5680,7 @@ async function cmdNotifyCursor(args) {
 }
 async function cmdNotifyd(rest) {
 	const sub = rest[0] ?? "status";
-	const daemon = await import("./notifyDaemon-849g16zO.js");
+	const daemon = await import("./notifyDaemon-BPpVmmj0.js");
 	switch (sub) {
 		case "run": return daemon.runDaemon();
 		case "once": return daemon.runDaemon({ once: true });
@@ -5179,4 +5707,4 @@ async function cmdNotifyd(rest) {
 
 //#endregion
 export { sendPayloadCapError as $, isUnknownManagerToken as A, readLogForRender as B, finalizedLines as C, isPidAlive as D, isExitRequest as E, listRecords as F, renderLogTailLines as G, readPtysize as H, matchKeyword as I, resolveOne as J, renderRawLog as K, menuSelectKeys as L, isUserTyping as M, lastReadAt as N, isSlashCommand as O, lastStdinAt as P, runSubcommand as Q, probeStdinReachable as R, extractTaskCounts as S, isBareManagerInvocation as T, recentMessageEdges as U, readNotes as V, recentReadEdges as W, resolveResumeArgs as X, resolveReadWindow as Y, restartHintLines as Z, envelopeAttribution as _, SEND_BODY_MAX_CHARS as a, writeKeysPaced as at, extractMenu as b, backoffWhileTyping as c, framePaste as ct, cmdHelp as d, buildAgentForest as dt, snapshotStatus as et, confirmStdinUnreachable as f, flattenForest as ft, deriveLiveStatus as g, deriveLiveState as h, READ_WINDOW_MS as i, waitForLogQuiet as it, isUnreachableWriteErrno as j, isSubcommand as k, buildEnvelope as l, shouldFramePaste as lt, cursorAbs as m, MAX_RENDER_BYTES as n, stopTipForCli as nt, SEND_EXIT_UNREACHABLE as o, writeToIpc as ot, controlCodeFromName as p, renderRawLogLines as q, READ_PAGE_DEFAULT as r, submitAndConfirm as rt, TYPING_WINDOW_MS as s, withIpcLock as st, GRACEFUL_EXIT_COMMANDS as t, stdinActivityPath as tt, cliDefaults as u, TYPING_BADGE as ut, envelopeCostFor as v, isAgentStuck as w, extractNeedsInput as x, extractBadges as y, readAgentPtysize as z };
-//# sourceMappingURL=subcommands-BFcfYykF.js.map
+//# sourceMappingURL=subcommands-DoKUSvaF.js.map