claude-yes 1.86.0 → 1.88.0

package/dist/{SUPPORTED_CLIS-5njwpFxr.js → SUPPORTED_CLIS-VbHPdSIt.js}

@@ -1,6 +1,6 @@
-import { t as CLIS_CONFIG } from "./ts-DVlEOYHB.js";
+import { t as CLIS_CONFIG } from "./ts-CDrRTQFz.js";
 import "./logger-B9h0djqx.js";
-import "./versionChecker-XivGWuhd.js";
+import "./versionChecker-BjRotlWY.js";
 import "./pidStore-C1JXxoPi.js";
 import "./globalPidIndex-Cr-g75QF.js";
 
@@ -9,4 +9,4 @@ const SUPPORTED_CLIS = Object.keys(CLIS_CONFIG);
 
 //#endregion
 export { SUPPORTED_CLIS };
-//# sourceMappingURL=SUPPORTED_CLIS-5njwpFxr.js.map
+//# sourceMappingURL=SUPPORTED_CLIS-VbHPdSIt.js.map

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { n as logger } from "./logger-B9h0djqx.js";
-import { i as versionString, n as displayVersion, r as getInstalledPackage, t as checkAndAutoUpdate } from "./versionChecker-XivGWuhd.js";
+import { i as versionString, n as displayVersion, r as getInstalledPackage, t as checkAndAutoUpdate } from "./versionChecker-BjRotlWY.js";
 import { argv } from "process";
 import { execFileSync, spawn } from "child_process";
 import ms from "ms";
@@ -480,8 +480,14 @@ function buildRustArgs(argv, cliFromScript, supportedClis) {
 	}
 }
 {
-	const { isSubcommand, runSubcommand } = await import("./subcommands-BDiS305D.js");
-	if (isSubcommand(process.argv[2])) {
+	const rawArg = process.argv[2];
+	const isHelpFlag = rawArg === "-h" || rawArg === "--help";
+	const { isSubcommand, runSubcommand, cmdHelp } = await import("./subcommands-Dnh67Qo3.js");
+	if (isHelpFlag && process.argv.length === 3) {
+		cmdHelp();
+		process.exit(0);
+	}
+	if (isSubcommand(rawArg)) {
 		const code = await runSubcommand(process.argv);
 		process.exit(code ?? 0);
 	}
@@ -509,7 +515,7 @@ if (config.useRust) {
 		}
 	}
 	if (rustBinary) {
-		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-5njwpFxr.js");
+		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-VbHPdSIt.js");
 		const rustArgs = buildRustArgs(process.argv, config.cli, SUPPORTED_CLIS);
 		if (config.verbose) {
 			console.log(`[rust] Using binary: ${rustBinary}`);

package/dist/index.js

@@ -1,6 +1,6 @@
-import { a as removeControlCharacters, i as AgentContext, n as agentYes, r as config, t as CLIS_CONFIG } from "./ts-DVlEOYHB.js";
+import { a as removeControlCharacters, i as AgentContext, n as agentYes, r as config, t as CLIS_CONFIG } from "./ts-CDrRTQFz.js";
 import "./logger-B9h0djqx.js";
-import "./versionChecker-XivGWuhd.js";
+import "./versionChecker-BjRotlWY.js";
 import "./pidStore-C1JXxoPi.js";
 import "./globalPidIndex-Cr-g75QF.js";
 

package/dist/{remotes-CFrho898.js → remotes-Bjp2GYPz.js}

@@ -79,11 +79,15 @@ async function resolveRemoteSpec(spec) {
 }
 async function cmdRemote(rest) {
 	const sub = rest[0];
+	if (sub === "-h" || sub === "--help") {
+		process.stdout.write("Usage: ay remote <subcommand>\n\nManage saved remote server aliases.\n\nSubcommands:\n  ay remote ls                                           list configured remotes\n  ay remote add <alias> http://<token>@<host>:<port>    add a remote\n  ay remote rm <alias>                                   remove a remote\n\nOnce added, use the alias anywhere a keyword is accepted:\n  ay ls   <alias>\n  ay tail <alias>:<keyword>\n  ay send <alias>:<keyword> \"message\"\n");
+		return 0;
+	}
 	if (!sub || sub === "ls" || sub === "list") {
 		const remotes = await readRemotes();
 		if (remotes.size === 0) {
 			process.stdout.write("no remotes configured\n");
-			process.stderr.write("\n  ay remote add <alias> <url> <token>   # add a remote\n  ay serve                               # start server (prints token)\n");
+			process.stderr.write("\n  ay remote add <alias> http://<token>@<host>:<port>   # add a remote\n  ay serve                                           # start server (prints token)\n");
 			return 0;
 		}
 		for (const [alias, cfg] of remotes) {
@@ -93,10 +97,25 @@ async function cmdRemote(rest) {
 		return 0;
 	}
 	if (sub === "add") {
-		const [, alias, url, token] = rest;
-		if (!alias || !url || !token) {
-			process.stderr.write("usage: ay remote add <alias> <url> <token>\n");
-			process.stderr.write("  example: ay remote add work-mac http://192.168.1.5:7432 mytoken123\n");
+		const [, alias, rawUrl] = rest;
+		if (!alias || !rawUrl) {
+			process.stderr.write("usage: ay remote add <alias> http://<token>@<host>:<port>\n");
+			process.stderr.write("  example: ay remote add work-mac http://mytoken123@192.168.1.5:7432\n");
+			return 1;
+		}
+		let url, token;
+		try {
+			const parsed = new URL(rawUrl);
+			token = parsed.username;
+			parsed.username = "";
+			parsed.password = "";
+			url = parsed.toString().replace(/\/$/, "");
+		} catch {
+			process.stderr.write(`ay remote add: invalid URL '${rawUrl}'\n`);
+			return 1;
+		}
+		if (!token) {
+			process.stderr.write(`ay remote add: no token in URL — expected http://<token>@<host>:<port>\n`);
 			return 1;
 		}
 		await writeRemoteAlias(alias, {
@@ -122,10 +141,10 @@ async function cmdRemote(rest) {
 		return 0;
 	}
 	process.stderr.write(`ay remote: unknown subcommand '${sub}'\n`);
-	process.stderr.write("  ay remote ls                           # list configured remotes\n  ay remote add <alias> <url> <token>   # add a remote\n  ay remote rm <alias>                   # remove a remote\n");
+	process.stderr.write("  ay remote ls                                           # list configured remotes\n  ay remote add <alias> http://<token>@<host>:<port>   # add a remote\n  ay remote rm <alias>                                  # remove a remote\n");
 	return 1;
 }
 
 //#endregion
 export { resolveRemoteSpec as a, readRemotes as i, deleteRemoteAlias as n, writeRemoteAlias as o, parseDirectRemoteSpec as r, cmdRemote as t };
-//# sourceMappingURL=remotes-CFrho898.js.map
+//# sourceMappingURL=remotes-Bjp2GYPz.js.map

package/dist/{remotes-kfUzk-JT.js → remotes-oNI1fR7_.js}

@@ -1,3 +1,3 @@
-import { a as resolveRemoteSpec, i as readRemotes, n as deleteRemoteAlias, o as writeRemoteAlias, r as parseDirectRemoteSpec, t as cmdRemote } from "./remotes-CFrho898.js";
+import { a as resolveRemoteSpec, i as readRemotes, n as deleteRemoteAlias, o as writeRemoteAlias, r as parseDirectRemoteSpec, t as cmdRemote } from "./remotes-Bjp2GYPz.js";
 
 export { cmdRemote };

package/dist/{serve-D0NnTXRD.js → serve-CAEEkFLd.js}

@@ -1,7 +1,7 @@
 import "./logger-B9h0djqx.js";
 import "./globalPidIndex-Cr-g75QF.js";
-import "./remotes-CFrho898.js";
-import { c as resolveOne, d as writeToIpc, i as listRecords, o as readNotes, s as renderRawLog, t as controlCodeFromName, u as snapshotStatus } from "./subcommands-BpGEGOQM.js";
+import "./remotes-Bjp2GYPz.js";
+import { a as listRecords, c as renderRawLog, d as snapshotStatus, f as writeToIpc, l as resolveOne, n as controlCodeFromName, s as readNotes } from "./subcommands-DIworIYh.js";
 import yargs from "yargs";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { homedir } from "os";
@@ -72,7 +72,8 @@ async function cmdServeDaemon(sub, args) {
 		if (code === 0) {
 			process.stdout.write(`\ninstalled '${DAEMON_NAME}' as a daemon via oxmgr\n`);
 			process.stdout.write(`token: ${token}\n\n`);
-			process.stdout.write(`  ay ls ${token}@<host>:${DEFAULT_PORT}\n`);
+			process.stdout.write(`  ay ls   ${token}@<host>:${DEFAULT_PORT}\n`);
+			process.stdout.write(`  ay remote add <alias> http://${token}@<host>:${DEFAULT_PORT}\n`);
 			process.stdout.write(`  ay serve logs                # view server logs\n`);
 			process.stdout.write(`  ay serve uninstall           # remove daemon\n`);
 		}
@@ -100,6 +101,15 @@ async function cmdServeDaemon(sub, args) {
 	return 1;
 }
 async function cmdServe(rest) {
+	if (rest.includes("-h") || rest.includes("--help")) {
+		process.stdout.write(`Usage: ay serve [options]
+
+Start an HTTP API server so remote machines can list/tail/send agents.
+
+Options:
+  --port N          Port to listen on (default: ${DEFAULT_PORT})\n  --host HOST       Interface to bind (default: 127.0.0.1; use 0.0.0.0 to expose)\n  --token TOKEN     Auth token (auto-generated and saved if omitted)\n  --tls-cert FILE   TLS certificate PEM\n  --tls-key  FILE   TLS private key PEM\n\nSubcommands:\n  ay serve install    install as background daemon via oxmgr\n  ay serve uninstall  remove daemon\n  ay serve logs       view daemon logs\n\nOnce running, connect from another machine:\n  ay ls   <token>@<host>:${DEFAULT_PORT}\n  ay remote add <alias> http://<token>@<host>:${DEFAULT_PORT}\n`);
+		return 0;
+	}
 	const sub = rest[0];
 	if (sub === "install" || sub === "uninstall" || sub === "logs") return cmdServeDaemon(sub, rest.slice(1));
 	const argv = await yargs(rest).usage("Usage: ay serve [options]").option("port", {
@@ -283,6 +293,8 @@ async function cmdServe(rest) {
 	process.stdout.write(`  ay ls   ${token}@<host>:${port}\n`);
 	process.stdout.write(`  ay tail ${token}@<host>:${port}:<keyword>\n`);
 	process.stdout.write(`  ay send ${token}@<host>:${port}:<keyword> "message"\n\n`);
+	process.stdout.write(`save as alias:\n`);
+	process.stdout.write(`  ay remote add <alias> ${scheme}://${token}@<host>:${port}\n\n`);
 	if (!useHttps) process.stdout.write("for HTTPS: ay serve --tls-cert cert.pem --tls-key key.pem\n  openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'\n\n");
 	process.stdout.write(`(Ctrl-C to stop)\n`);
 	await new Promise((resolve) => {
@@ -300,4 +312,4 @@ async function cmdServe(rest) {
 
 //#endregion
 export { cmdServe };
-//# sourceMappingURL=serve-D0NnTXRD.js.map
+//# sourceMappingURL=serve-CAEEkFLd.js.map

package/dist/{subcommands-BpGEGOQM.js → subcommands-DIworIYh.js}

@@ -1,5 +1,6 @@
 import { r as readGlobalPids } from "./globalPidIndex-Cr-g75QF.js";
-import { a as resolveRemoteSpec, i as readRemotes } from "./remotes-CFrho898.js";
+import { a as resolveRemoteSpec, i as readRemotes } from "./remotes-Bjp2GYPz.js";
+import ms from "ms";
 import yargs from "yargs";
 import { appendFile, mkdir, open, readFile, stat, writeFile } from "fs/promises";
 import { homedir } from "os";
@@ -128,7 +129,8 @@ const SUBCOMMANDS = new Set([
 	"restart",
 	"note",
 	"serve",
-	"remote"
+	"remote",
+	"help"
 ]);
 const IDLE_THRESHOLD_MS = 60 * 1e3;
 function isSubcommand(name) {
@@ -156,13 +158,14 @@ async function runSubcommand(argv) {
 			case "restart": return await cmdRestart(rest);
 			case "note": return await cmdNote(rest);
 			case "serve": {
-				const { cmdServe } = await import("./serve-D0NnTXRD.js");
+				const { cmdServe } = await import("./serve-CAEEkFLd.js");
 				return cmdServe(rest);
 			}
 			case "remote": {
-				const { cmdRemote } = await import("./remotes-kfUzk-JT.js");
+				const { cmdRemote } = await import("./remotes-oNI1fR7_.js");
 				return cmdRemote(rest);
 			}
+			case "help": return cmdHelp();
 			default: return null;
 		}
 	} catch (err) {
@@ -171,6 +174,10 @@ async function runSubcommand(argv) {
 		return 1;
 	}
 }
+function cmdHelp() {
+	process.stdout.write("ay - agent-yes CLI\n\nManagement:\n  ay ls [keyword]                     list running agents\n  ay tail [-f] <keyword>              stream output  (Ctrl-C to stop)\n  ay cat <keyword>                    full log\n  ay head <keyword>                   first N lines\n  ay send <keyword> <msg>             send a message\n  ay status <keyword>                 agent status snapshot\n\nRemote:\n  ay serve [--port N]                 start HTTP API server (prints token)\n  ay remote add <alias> http://<token>@<host>:<port>\n  ay remote ls / rm <alias>           manage saved remotes\n  ay ls   <token>@<host>:<port>       connect inline (no alias needed)\n  ay send <token>@<host>:<port>:<kw> <msg>\n\nRun an agent:\n  ay [claude|codex|gemini|...] [options] -- [prompt]\n  ay claude -- \"fix the bug in auth.ts\"\n  ay claude --help                    full agent-runner options\n\nLabs (examples in ./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) {
 	if (!keyword) return true;
 	const kw = keyword.toLowerCase();
@@ -200,12 +207,70 @@ function isPidAlive(pid) {
 		return false;
 	}
 }
+async function pickInteractive(matches) {
+	const list = matches.slice(0, 10);
+	let sel = 0;
+	const render = () => {
+		for (let i = 0; i < list.length; i++) {
+			const r = list[i];
+			const marker = i === sel ? "\x1B[36m>\x1B[0m" : " ";
+			process.stderr.write(`${marker} ${r.pid}  ${r.cli}  ${r.cwd}\n`);
+		}
+	};
+	process.stderr.write(`Multiple matches — select with ↑↓ Enter (or type 1-${list.length}):\n`);
+	render();
+	return new Promise((resolve) => {
+		process.stdin.setRawMode(true);
+		process.stdin.resume();
+		process.stdin.setEncoding("utf8");
+		const redraw = () => {
+			process.stderr.write(`\x1b[${list.length}A\x1b[0J`);
+			render();
+		};
+		const cleanup = () => {
+			process.stdin.off("data", onData);
+			try {
+				process.stdin.setRawMode(false);
+			} catch {}
+			process.stdin.pause();
+		};
+		const onData = (key) => {
+			if (key === "") {
+				cleanup();
+				process.stderr.write("\n");
+				resolve(null);
+			} else if (key === "\r" || key === "\n") {
+				cleanup();
+				process.stderr.write("\n");
+				resolve(list[sel]);
+			} else if (key === "\x1B[A") {
+				sel = Math.max(0, sel - 1);
+				redraw();
+			} else if (key === "\x1B[B") {
+				sel = Math.min(list.length - 1, sel + 1);
+				redraw();
+			} else if (key >= "1" && key <= String(list.length)) {
+				sel = parseInt(key, 10) - 1;
+				redraw();
+				cleanup();
+				process.stderr.write("\n");
+				resolve(list[sel]);
+			}
+		};
+		process.stdin.on("data", onData);
+	});
+}
 async function resolveOne(keyword, opts) {
 	if (!keyword) throw new Error("keyword required (pid, cwd substring, cli name, or prompt substring)");
 	const matches = await listRecords(keyword, opts);
 	if (matches.length === 0) throw new Error(`no agent matched "${keyword}"`);
 	if (matches.length === 1) return matches[0];
 	if (opts.latest) return matches[0];
+	if (process.stderr.isTTY && process.stdin.isTTY) {
+		const chosen = await pickInteractive(matches);
+		if (chosen) return chosen;
+		throw new Error("no agent selected");
+	}
 	const lines = matches.slice(0, 10).map((r) => `  ${r.pid}  ${r.cli}  ${r.cwd}`).join("\n");
 	throw new Error(`keyword "${keyword}" matched ${matches.length} agents — disambiguate by pid or pass --latest:\n${lines}`);
 }
@@ -583,6 +648,7 @@ async function cmdLs(rest) {
 		if (alive) {
 			hints.push(`  ay status ${alive.pid}                # JSON status snapshot\n`);
 			hints.push(`  ay status ${alive.pid} --watch        # stream changes as JSON\n`);
+			hints.push(`  ay status ${alive.pid} --wait-idle    # block until state == idle\n`);
 			hints.push(`  ay tail ${alive.pid}                  # view latest output\n`);
 			hints.push(`  ay tail -f ${alive.pid}               # follow live output\n`);
 			hints.push(`  ay send ${alive.pid} "next: ..."      # send a prompt (keyword: pid, cwd, or prompt substring)\n`);
@@ -1012,6 +1078,13 @@ async function cmdStatus(rest) {
 		type: "boolean",
 		default: false,
 		description: "Stream changes as JSON"
+	}).option("wait-idle", {
+		type: "boolean",
+		default: false,
+		description: "Block until state == idle. Exit 0 idle, 1 stopped, 2 timeout"
+	}).option("timeout", {
+		type: "string",
+		description: "Timeout for --wait-idle (e.g. 30s, 5m). Default: no timeout"
 	}).option("interval", {
 		type: "number",
 		default: 2,
@@ -1032,14 +1105,17 @@ async function cmdStatus(rest) {
 		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
 	};
 	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
-	if (!keyword) throw new Error("usage: ay status <keyword> [--watch] [--interval=N]");
+	if (!keyword) throw new Error("usage: ay status <keyword> [--watch | --wait-idle] [--timeout=Ns]");
 	{
 		const remote = await resolveRemoteSpec(keyword);
 		if (remote) return runRemoteStatus(remote);
 	}
 	const watch = argv.watch;
+	const waitIdle = argv["wait-idle"];
 	const intervalFlag = argv.interval;
 	const intervalMs = Math.max(500, (Number.isFinite(intervalFlag) ? intervalFlag : 2) * 1e3);
+	const timeoutMs = typeof argv.timeout === "string" && argv.timeout.length > 0 ? ms(argv.timeout) ?? NaN : null;
+	if (timeoutMs !== null && !Number.isFinite(timeoutMs)) throw new Error(`invalid --timeout value: ${argv.timeout}`);
 	const record = await resolveOne(keyword, opts);
 	const emit = (snap, ts) => {
 		const out = ts !== void 0 ? {
@@ -1048,6 +1124,25 @@ async function cmdStatus(rest) {
 		} : snap;
 		process.stdout.write(JSON.stringify(out) + "\n");
 	};
+	if (waitIdle) {
+		const startedAt = Date.now();
+		for (;;) {
+			const snap = await snapshotStatus(record);
+			if (snap.state === "idle") {
+				emit(snap);
+				return 0;
+			}
+			if (snap.state === "stopped") {
+				emit(snap);
+				return 1;
+			}
+			if (timeoutMs !== null && Date.now() - startedAt >= timeoutMs) {
+				emit(snap);
+				return 2;
+			}
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+	}
 	if (!watch) {
 		emit(await snapshotStatus(record));
 		return 0;
@@ -1077,5 +1172,5 @@ async function cmdStatus(rest) {
 }
 
 //#endregion
-export { matchKeyword as a, resolveOne as c, writeToIpc as d, listRecords as i, runSubcommand as l, isPidAlive as n, readNotes as o, isSubcommand as r, renderRawLog as s, controlCodeFromName as t, snapshotStatus as u };
-//# sourceMappingURL=subcommands-BpGEGOQM.js.map
+export { listRecords as a, renderRawLog as c, snapshotStatus as d, writeToIpc as f, isSubcommand as i, resolveOne as l, controlCodeFromName as n, matchKeyword as o, isPidAlive as r, readNotes as s, cmdHelp as t, runSubcommand as u };
+//# sourceMappingURL=subcommands-DIworIYh.js.map

package/dist/subcommands-Dnh67Qo3.js

@@ -0,0 +1,6 @@
+import "./logger-B9h0djqx.js";
+import "./globalPidIndex-Cr-g75QF.js";
+import "./remotes-Bjp2GYPz.js";
+import { a as listRecords, c as renderRawLog, d as snapshotStatus, f as writeToIpc, i as isSubcommand, l as resolveOne, n as controlCodeFromName, o as matchKeyword, r as isPidAlive, s as readNotes, t as cmdHelp, u as runSubcommand } from "./subcommands-DIworIYh.js";
+
+export { cmdHelp, isSubcommand, runSubcommand };

package/dist/{ts-DVlEOYHB.js → ts-CDrRTQFz.js}

@@ -1,5 +1,5 @@
 import { n as logger, t as addTransport } from "./logger-B9h0djqx.js";
-import { r as getInstalledPackage } from "./versionChecker-XivGWuhd.js";
+import { r as getInstalledPackage } from "./versionChecker-BjRotlWY.js";
 import { i as shouldUseLock, r as releaseLock, t as acquireLock } from "./runningLock-C22d9SRJ.js";
 import { t as PidStore } from "./pidStore-C1JXxoPi.js";
 import { r as readGlobalPids } from "./globalPidIndex-Cr-g75QF.js";
@@ -1693,4 +1693,4 @@ function sleep(ms) {
 
 //#endregion
 export { removeControlCharacters as a, AgentContext as i, agentYes as n, config as r, CLIS_CONFIG as t };
-//# sourceMappingURL=ts-DVlEOYHB.js.map
+//# sourceMappingURL=ts-CDrRTQFz.js.map

package/dist/{versionChecker-XivGWuhd.js → versionChecker-BjRotlWY.js}

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 
 //#region package.json
 var name = "claude-yes";
-var version = "1.86.0";
+var version = "1.88.0";
 
 //#endregion
 //#region ts/versionChecker.ts
@@ -221,4 +221,4 @@ async function displayVersion() {
 
 //#endregion
 export { versionString as i, displayVersion as n, getInstalledPackage as r, checkAndAutoUpdate as t };
-//# sourceMappingURL=versionChecker-XivGWuhd.js.map
+//# sourceMappingURL=versionChecker-BjRotlWY.js.map

package/package.json

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

package/ts/cli.ts

@@ -20,8 +20,15 @@ import { buildRustArgs } from "./buildRustArgs.ts";
 // agent-spawn machinery (and the --rust dispatch) and operate on the global
 // pid index instead. Must run before checkAndAutoUpdate / yargs / Rust spawn.
 {
-  const { isSubcommand, runSubcommand } = await import("./subcommands.ts");
-  if (isSubcommand(process.argv[2])) {
+  const rawArg = process.argv[2];
+  // Intercept bare -h/--help so we show TS subcommands, not just Rust agent-runner options.
+  const isHelpFlag = rawArg === "-h" || rawArg === "--help";
+  const { isSubcommand, runSubcommand, cmdHelp } = await import("./subcommands.ts");
+  if (isHelpFlag && process.argv.length === 3) {
+    cmdHelp();
+    process.exit(0);
+  }
+  if (isSubcommand(rawArg)) {
     const code = await runSubcommand(process.argv);
     process.exit(code ?? 0);
   }

package/ts/remotes.ts

@@ -102,14 +102,30 @@ export async function resolveRemoteSpec(spec: string): Promise<ResolvedRemote |
 export async function cmdRemote(rest: string[]): Promise<number> {
   const sub = rest[0];
 
+  if (sub === "-h" || sub === "--help") {
+    process.stdout.write(
+      `Usage: ay remote <subcommand>\n\n` +
+        `Manage saved remote server aliases.\n\n` +
+        `Subcommands:\n` +
+        `  ay remote ls                                           list configured remotes\n` +
+        `  ay remote add <alias> http://<token>@<host>:<port>    add a remote\n` +
+        `  ay remote rm <alias>                                   remove a remote\n\n` +
+        `Once added, use the alias anywhere a keyword is accepted:\n` +
+        `  ay ls   <alias>\n` +
+        `  ay tail <alias>:<keyword>\n` +
+        `  ay send <alias>:<keyword> "message"\n`,
+    );
+    return 0;
+  }
+
   if (!sub || sub === "ls" || sub === "list") {
     const remotes = await readRemotes();
     if (remotes.size === 0) {
       process.stdout.write("no remotes configured\n");
       process.stderr.write(
         "\n" +
-          "  ay remote add <alias> <url> <token>   # add a remote\n" +
-          "  ay serve                               # start server (prints token)\n",
+          "  ay remote add <alias> http://<token>@<host>:<port>   # add a remote\n" +
+          "  ay serve                                           # start server (prints token)\n",
       );
       return 0;
     }
@@ -121,11 +137,28 @@ export async function cmdRemote(rest: string[]): Promise<number> {
   }
 
   if (sub === "add") {
-    const [, alias, url, token] = rest;
-    if (!alias || !url || !token) {
-      process.stderr.write("usage: ay remote add <alias> <url> <token>\n");
+    const [, alias, rawUrl] = rest;
+    if (!alias || !rawUrl) {
+      process.stderr.write("usage: ay remote add <alias> http://<token>@<host>:<port>\n");
+      process.stderr.write(
+        "  example: ay remote add work-mac http://mytoken123@192.168.1.5:7432\n",
+      );
+      return 1;
+    }
+    let url: string, token: string;
+    try {
+      const parsed = new URL(rawUrl);
+      token = parsed.username;
+      parsed.username = "";
+      parsed.password = "";
+      url = parsed.toString().replace(/\/$/, "");
+    } catch {
+      process.stderr.write(`ay remote add: invalid URL '${rawUrl}'\n`);
+      return 1;
+    }
+    if (!token) {
       process.stderr.write(
-        "  example: ay remote add work-mac http://192.168.1.5:7432 mytoken123\n",
+        `ay remote add: no token in URL — expected http://<token>@<host>:<port>\n`,
       );
       return 1;
     }
@@ -153,9 +186,9 @@ export async function cmdRemote(rest: string[]): Promise<number> {
 
   process.stderr.write(`ay remote: unknown subcommand '${sub}'\n`);
   process.stderr.write(
-    "  ay remote ls                           # list configured remotes\n" +
-      "  ay remote add <alias> <url> <token>   # add a remote\n" +
-      "  ay remote rm <alias>                   # remove a remote\n",
+    "  ay remote ls                                           # list configured remotes\n" +
+      "  ay remote add <alias> http://<token>@<host>:<port>   # add a remote\n" +
+      "  ay remote rm <alias>                                  # remove a remote\n",
   );
   return 1;
 }

package/ts/serve.ts

@@ -85,7 +85,8 @@ async function cmdServeDaemon(sub: string, args: string[]): Promise<number> {
     if (code === 0) {
       process.stdout.write(`\ninstalled '${DAEMON_NAME}' as a daemon via oxmgr\n`);
       process.stdout.write(`token: ${token}\n\n`);
-      process.stdout.write(`  ay ls ${token}@<host>:${DEFAULT_PORT}\n`);
+      process.stdout.write(`  ay ls   ${token}@<host>:${DEFAULT_PORT}\n`);
+      process.stdout.write(`  ay remote add <alias> http://${token}@<host>:${DEFAULT_PORT}\n`);
       process.stdout.write(`  ay serve logs                # view server logs\n`);
       process.stdout.write(`  ay serve uninstall           # remove daemon\n`);
     }
@@ -114,6 +115,27 @@ async function cmdServeDaemon(sub: string, args: string[]): Promise<number> {
 // ---------------------------------------------------------------------------
 
 export async function cmdServe(rest: string[]): Promise<number> {
+  if (rest.includes("-h") || rest.includes("--help")) {
+    process.stdout.write(
+      `Usage: ay serve [options]\n\n` +
+        `Start an HTTP API server so remote machines can list/tail/send agents.\n\n` +
+        `Options:\n` +
+        `  --port N          Port to listen on (default: ${DEFAULT_PORT})\n` +
+        `  --host HOST       Interface to bind (default: 127.0.0.1; use 0.0.0.0 to expose)\n` +
+        `  --token TOKEN     Auth token (auto-generated and saved if omitted)\n` +
+        `  --tls-cert FILE   TLS certificate PEM\n` +
+        `  --tls-key  FILE   TLS private key PEM\n\n` +
+        `Subcommands:\n` +
+        `  ay serve install    install as background daemon via oxmgr\n` +
+        `  ay serve uninstall  remove daemon\n` +
+        `  ay serve logs       view daemon logs\n\n` +
+        `Once running, connect from another machine:\n` +
+        `  ay ls   <token>@<host>:${DEFAULT_PORT}\n` +
+        `  ay remote add <alias> http://<token>@<host>:${DEFAULT_PORT}\n`,
+    );
+    return 0;
+  }
+
   // Daemon subcommands
   const sub = rest[0];
   if (sub === "install" || sub === "uninstall" || sub === "logs") {
@@ -350,6 +372,8 @@ export async function cmdServe(rest: string[]): Promise<number> {
   process.stdout.write(`  ay ls   ${token}@<host>:${port}\n`);
   process.stdout.write(`  ay tail ${token}@<host>:${port}:<keyword>\n`);
   process.stdout.write(`  ay send ${token}@<host>:${port}:<keyword> "message"\n\n`);
+  process.stdout.write(`save as alias:\n`);
+  process.stdout.write(`  ay remote add <alias> ${scheme}://${token}@<host>:${port}\n\n`);
   if (!useHttps) {
     process.stdout.write(
       `for HTTPS: ay serve --tls-cert cert.pem --tls-key key.pem\n` +

package/ts/subcommands.spec.ts

@@ -926,6 +926,109 @@ describe("subcommands.cmdStatus", () => {
     expect(snap).toMatchObject({ pid: process.pid, cli: "claude" });
     expect(typeof snap.age_ms).toBe("number");
   });
+
+  it("--wait-idle returns 0 immediately for an idle agent", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const logFile = path.join(testHome, "idle.raw.log");
+    await writeFile(logFile, "old\n");
+    // Stale mtime: > IDLE_THRESHOLD_MS (60s) in the past
+    const stale = (Date.now() - 5 * 60 * 1000) / 1000;
+    const { utimes } = await import("fs/promises");
+    await utimes(logFile, stale, stale);
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "wait-idle-test",
+      cwd: process.cwd(),
+      log_file: logFile,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now() - 10_000,
+    });
+
+    const stdout: string[] = [];
+    (process.stdout as any).write = (s: any) => {
+      stdout.push(String(s));
+      return true;
+    };
+    (process.stderr as any).write = () => true;
+    const code = await mod.runSubcommand([
+      "bun",
+      "cli.js",
+      "status",
+      String(process.pid),
+      "--wait-idle",
+      "--timeout=2s",
+      "--interval=0.5",
+    ]);
+    expect(code).toBe(0);
+    const snap = JSON.parse(stdout.join("").trim().split("\n").pop()!);
+    expect(snap.state).toBe("idle");
+  });
+
+  it("--wait-idle returns 1 when the agent is stopped", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    // Pick a pid that is almost certainly not alive.
+    const deadPid = 999_999;
+    await appendGlobalPid({
+      pid: deadPid,
+      cli: "claude",
+      prompt: "wait-idle-stopped",
+      cwd: process.cwd(),
+      log_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now() - 10_000,
+    });
+
+    (process.stdout as any).write = () => true;
+    (process.stderr as any).write = () => true;
+    const code = await mod.runSubcommand([
+      "bun",
+      "cli.js",
+      "status",
+      String(deadPid),
+      "--wait-idle",
+      "--interval=0.5",
+    ]);
+    expect(code).toBe(1);
+  });
+
+  it("--wait-idle returns 2 on timeout while still active", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const logFile = path.join(testHome, "active.raw.log");
+    await writeFile(logFile, "fresh\n");
+    // Fresh mtime keeps state = active
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "wait-idle-timeout",
+      cwd: process.cwd(),
+      log_file: logFile,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now() - 10_000,
+    });
+
+    (process.stdout as any).write = () => true;
+    (process.stderr as any).write = () => true;
+    const code = await mod.runSubcommand([
+      "bun",
+      "cli.js",
+      "status",
+      String(process.pid),
+      "--wait-idle",
+      "--timeout=600ms",
+      "--interval=0.5",
+    ]);
+    expect(code).toBe(2);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/ts/subcommands.ts

@@ -12,6 +12,7 @@
  */
 
 import { appendFile, mkdir, open, readFile, stat, writeFile } from "fs/promises";
+import ms from "ms";
 import { homedir } from "os";
 import path from "path";
 import { type GlobalPidRecord, readGlobalPids } from "./globalPidIndex.ts";
@@ -139,6 +140,7 @@ const SUBCOMMANDS = new Set([
   "note",
   "serve",
   "remote",
+  "help",
 ]);
 
 const IDLE_THRESHOLD_MS = 60 * 1000;
@@ -186,6 +188,8 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
         const { cmdRemote } = await import("./remotes.ts");
         return cmdRemote(rest);
       }
+      case "help":
+        return cmdHelp();
       default:
         return null;
     }
@@ -196,6 +200,42 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
   }
 }
 
+// ---------------------------------------------------------------------------
+// ay help
+// ---------------------------------------------------------------------------
+
+export function cmdHelp(): number {
+  process.stdout.write(
+    `ay - agent-yes CLI\n` +
+      `\n` +
+      `Management:\n` +
+      `  ay ls [keyword]                     list running agents\n` +
+      `  ay tail [-f] <keyword>              stream output  (Ctrl-C to stop)\n` +
+      `  ay cat <keyword>                    full log\n` +
+      `  ay head <keyword>                   first N lines\n` +
+      `  ay send <keyword> <msg>             send a message\n` +
+      `  ay status <keyword>                 agent status snapshot\n` +
+      `\n` +
+      `Remote:\n` +
+      `  ay serve [--port N]                 start HTTP API server (prints token)\n` +
+      `  ay remote add <alias> http://<token>@<host>:<port>\n` +
+      `  ay remote ls / rm <alias>           manage saved remotes\n` +
+      `  ay ls   <token>@<host>:<port>       connect inline (no alias needed)\n` +
+      `  ay send <token>@<host>:<port>:<kw> <msg>\n` +
+      `\n` +
+      `Run an agent:\n` +
+      `  ay [claude|codex|gemini|...] [options] -- [prompt]\n` +
+      `  ay claude -- "fix the bug in auth.ts"\n` +
+      `  ay claude --help                    full agent-runner options\n` +
+      `\n` +
+      `Labs (examples in ./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;
+}
+
 // ---------------------------------------------------------------------------
 // shared helpers
 // ---------------------------------------------------------------------------
@@ -260,6 +300,69 @@ export function isPidAlive(pid: number): boolean {
   }
 }
 
+async function pickInteractive(matches: GlobalPidRecord[]): Promise<GlobalPidRecord | null> {
+  const list = matches.slice(0, 10);
+  let sel = 0;
+
+  const render = () => {
+    for (let i = 0; i < list.length; i++) {
+      const r = list[i]!;
+      const marker = i === sel ? "\x1b[36m>\x1b[0m" : " ";
+      process.stderr.write(`${marker} ${r.pid}  ${r.cli}  ${r.cwd}\n`);
+    }
+  };
+
+  process.stderr.write(`Multiple matches — select with ↑↓ Enter (or type 1-${list.length}):\n`);
+  render();
+
+  return new Promise((resolve) => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    const redraw = () => {
+      process.stderr.write(`\x1b[${list.length}A\x1b[0J`);
+      render();
+    };
+
+    const cleanup = () => {
+      process.stdin.off("data", onData);
+      try {
+        process.stdin.setRawMode(false);
+      } catch {
+        /* not a tty */
+      }
+      process.stdin.pause();
+    };
+
+    const onData = (key: string) => {
+      if (key === "\x03") {
+        cleanup();
+        process.stderr.write("\n");
+        resolve(null);
+      } else if (key === "\r" || key === "\n") {
+        cleanup();
+        process.stderr.write("\n");
+        resolve(list[sel]!);
+      } else if (key === "\x1b[A") {
+        sel = Math.max(0, sel - 1);
+        redraw();
+      } else if (key === "\x1b[B") {
+        sel = Math.min(list.length - 1, sel + 1);
+        redraw();
+      } else if (key >= "1" && key <= String(list.length)) {
+        sel = parseInt(key, 10) - 1;
+        redraw();
+        cleanup();
+        process.stderr.write("\n");
+        resolve(list[sel]!);
+      }
+    };
+
+    process.stdin.on("data", onData);
+  });
+}
+
 export async function resolveOne(
   keyword: string | undefined,
   opts: CommonOpts,
@@ -273,6 +376,11 @@ export async function resolveOne(
   }
   if (matches.length === 1) return matches[0]!;
   if (opts.latest) return matches[0]!; // already sorted newest-first
+  if (process.stderr.isTTY && process.stdin.isTTY) {
+    const chosen = await pickInteractive(matches);
+    if (chosen) return chosen;
+    throw new Error("no agent selected");
+  }
   const lines = matches
     .slice(0, 10)
     .map((r) => `  ${r.pid}  ${r.cli}  ${r.cwd}`)
@@ -767,6 +875,7 @@ async function cmdLs(rest: string[]): Promise<number> {
     if (alive) {
       hints.push(`  ay status ${alive.pid}                # JSON status snapshot\n`);
       hints.push(`  ay status ${alive.pid} --watch        # stream changes as JSON\n`);
+      hints.push(`  ay status ${alive.pid} --wait-idle    # block until state == idle\n`);
       hints.push(`  ay tail ${alive.pid}                  # view latest output\n`);
       hints.push(`  ay tail -f ${alive.pid}               # follow live output\n`);
       hints.push(
@@ -1398,6 +1507,15 @@ async function cmdStatus(rest: string[]): Promise<number> {
       default: false,
       description: "Stream changes as JSON",
     })
+    .option("wait-idle", {
+      type: "boolean",
+      default: false,
+      description: "Block until state == idle. Exit 0 idle, 1 stopped, 2 timeout",
+    })
+    .option("timeout", {
+      type: "string",
+      description: "Timeout for --wait-idle (e.g. 30s, 5m). Default: no timeout",
+    })
     .option("interval", { type: "number", default: 2, description: "Poll interval in seconds" })
     .option("latest", { type: "boolean", default: false, description: "Use most recent match" })
     .option("cwd", { type: "string", description: "Restrict to agents under this dir" })
@@ -1415,7 +1533,8 @@ async function cmdStatus(rest: string[]): Promise<number> {
   };
   const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
 
-  if (!keyword) throw new Error("usage: ay status <keyword> [--watch] [--interval=N]");
+  if (!keyword)
+    throw new Error("usage: ay status <keyword> [--watch | --wait-idle] [--timeout=Ns]");
 
   {
     const remote = await resolveRemoteSpec(keyword);
@@ -1423,8 +1542,16 @@ async function cmdStatus(rest: string[]): Promise<number> {
   }
 
   const watch = argv.watch;
+  const waitIdle = argv["wait-idle"];
   const intervalFlag = argv.interval;
   const intervalMs = Math.max(500, (Number.isFinite(intervalFlag) ? intervalFlag : 2) * 1000);
+  const timeoutMs =
+    typeof argv.timeout === "string" && argv.timeout.length > 0
+      ? (ms(argv.timeout) ?? Number.NaN)
+      : null;
+  if (timeoutMs !== null && !Number.isFinite(timeoutMs)) {
+    throw new Error(`invalid --timeout value: ${argv.timeout}`);
+  }
 
   const record = await resolveOne(keyword, opts);
 
@@ -1433,6 +1560,26 @@ async function cmdStatus(rest: string[]): Promise<number> {
     process.stdout.write(JSON.stringify(out) + "\n");
   };
 
+  if (waitIdle) {
+    const startedAt = Date.now();
+    for (;;) {
+      const snap = await snapshotStatus(record);
+      if (snap.state === "idle") {
+        emit(snap);
+        return 0;
+      }
+      if (snap.state === "stopped") {
+        emit(snap);
+        return 1;
+      }
+      if (timeoutMs !== null && Date.now() - startedAt >= timeoutMs) {
+        emit(snap);
+        return 2;
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+
   if (!watch) {
     emit(await snapshotStatus(record));
     return 0;

package/dist/subcommands-BDiS305D.js

@@ -1,6 +0,0 @@
-import "./logger-B9h0djqx.js";
-import "./globalPidIndex-Cr-g75QF.js";
-import "./remotes-CFrho898.js";
-import { a as matchKeyword, c as resolveOne, d as writeToIpc, i as listRecords, l as runSubcommand, n as isPidAlive, o as readNotes, r as isSubcommand, s as renderRawLog, t as controlCodeFromName, u as snapshotStatus } from "./subcommands-BpGEGOQM.js";
-
-export { isSubcommand, runSubcommand };