claude-yes 1.84.0 → 1.85.0

package/dist/{SUPPORTED_CLIS-DM0fJTMR.js → SUPPORTED_CLIS-DnCV2Fj1.js}

@@ -1,6 +1,6 @@
-import { t as CLIS_CONFIG } from "./ts-Bw6gQKyU.js";
+import { t as CLIS_CONFIG } from "./ts-BTCVz_nZ.js";
 import "./logger-B9h0djqx.js";
-import "./versionChecker-CspuhOwO.js";
+import "./versionChecker-Cir2ZoFL.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-DM0fJTMR.js.map
+//# sourceMappingURL=SUPPORTED_CLIS-DnCV2Fj1.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-CspuhOwO.js";
+import { i as versionString, n as displayVersion, r as getInstalledPackage, t as checkAndAutoUpdate } from "./versionChecker-Cir2ZoFL.js";
 import { argv } from "process";
 import { execFileSync, spawn } from "child_process";
 import ms from "ms";
@@ -480,7 +480,7 @@ function buildRustArgs(argv, cliFromScript, supportedClis) {
 	}
 }
 {
-	const { isSubcommand, runSubcommand } = await import("./subcommands-DjO8lthH.js");
+	const { isSubcommand, runSubcommand } = await import("./subcommands-BwWcA9uo.js");
 	if (isSubcommand(process.argv[2])) {
 		const code = await runSubcommand(process.argv);
 		process.exit(code ?? 0);
@@ -509,7 +509,7 @@ if (config.useRust) {
 		}
 	}
 	if (rustBinary) {
-		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-DM0fJTMR.js");
+		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-DnCV2Fj1.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-Bw6gQKyU.js";
+import { a as removeControlCharacters, i as AgentContext, n as agentYes, r as config, t as CLIS_CONFIG } from "./ts-BTCVz_nZ.js";
 import "./logger-B9h0djqx.js";
-import "./versionChecker-CspuhOwO.js";
+import "./versionChecker-Cir2ZoFL.js";
 import "./pidStore-C1JXxoPi.js";
 import "./globalPidIndex-Cr-g75QF.js";
 

package/dist/{subcommands-DjO8lthH.js → subcommands-BwWcA9uo.js}

@@ -1,5 +1,6 @@
 import "./logger-B9h0djqx.js";
 import { r as readGlobalPids } from "./globalPidIndex-Cr-g75QF.js";
+import yargs from "yargs";
 import { appendFile, mkdir, open, readFile, stat, writeFile } from "fs/promises";
 import { homedir } from "os";
 import path from "path";
@@ -160,50 +161,6 @@ async function runSubcommand(argv) {
 		return 1;
 	}
 }
-function parseArgs(rest) {
-	const flags = {};
-	const positional = [];
-	for (let i = 0; i < rest.length; i++) {
-		const arg = rest[i];
-		if (arg.startsWith("--")) {
-			const eq = arg.indexOf("=");
-			if (eq >= 0) flags[arg.slice(2, eq)] = arg.slice(eq + 1);
-			else {
-				const key = arg.slice(2);
-				const next = rest[i + 1];
-				if ([
-					"all",
-					"active",
-					"follow",
-					"json",
-					"latest",
-					"watch"
-				].includes(key) || !next || next.startsWith("-")) flags[key] = true;
-				else {
-					flags[key] = next;
-					i++;
-				}
-			}
-		} else if (arg.startsWith("-") && arg.length > 1) if (arg === "-n") {
-			flags["n"] = rest[i + 1] ?? "";
-			i++;
-		} else flags[arg.slice(1)] = true;
-		else positional.push(arg);
-	}
-	return {
-		flags,
-		positional
-	};
-}
-function commonOpts(flags) {
-	return {
-		all: !!flags.all,
-		active: !!flags.active,
-		cwdScope: typeof flags.cwd === "string" ? path.resolve(flags.cwd) : flags.cwd === true ? process.cwd() : null,
-		latest: !!flags.latest,
-		json: !!flags.json
-	};
-}
 function matchKeyword(record, keyword) {
 	if (!keyword) return true;
 	const kw = keyword.toLowerCase();
@@ -243,9 +200,44 @@ async function resolveOne(keyword, opts) {
 	throw new Error(`keyword "${keyword}" matched ${matches.length} agents — disambiguate by pid or pass --latest:\n${lines}`);
 }
 async function cmdLs(rest) {
-	const { flags, positional } = parseArgs(rest);
-	const opts = commonOpts(flags);
-	const keyword = positional[0];
+	const y = yargs(rest).usage("Usage: ay ls [keyword] [options]\n       ay list [keyword] [options]\n       ay ps   [keyword] [options]\n\nList running agents. Optionally filter by keyword (pid, cwd substring, or prompt substring).").option("all", {
+		type: "boolean",
+		default: false,
+		description: "Show all agents including exited ones"
+	}).option("active", {
+		type: "boolean",
+		default: false,
+		description: "Only show agents with an alive process"
+	}).option("json", {
+		type: "boolean",
+		default: false,
+		description: "Output as JSON array"
+	}).option("latest", {
+		type: "boolean",
+		default: false,
+		description: "Show only the most recent agent"
+	}).option("cwd", {
+		type: "string",
+		description: "Restrict to agents whose cwd starts with dir"
+	}).option("help", {
+		alias: "h",
+		type: "boolean",
+		default: false,
+		description: "Show this help"
+	}).example("ay ls", "list running agents").example("ay ls --all", "include exited agents").example("ay ls --json", "machine-readable output").example("ay ls symval", "filter by cwd/prompt keyword").help(false).version(false).exitProcess(false);
+	const argv = await y.parseAsync();
+	if (argv.help || argv.h) {
+		process.stdout.write(await y.getHelp() + "\n");
+		return 0;
+	}
+	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	const opts = {
+		all: argv.all,
+		active: argv.active,
+		json: argv.json,
+		latest: argv.latest,
+		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
+	};
 	const records = await listRecords(keyword, opts);
 	if (opts.json) {
 		process.stdout.write(JSON.stringify(records, null, 2) + "\n");
@@ -349,11 +341,36 @@ function truncate(s, n) {
 	return s.slice(0, n - 1) + "…";
 }
 async function cmdRead(rest, { mode }) {
-	const { flags, positional } = parseArgs(rest);
-	const opts = commonOpts(flags);
-	const keyword = positional[0];
-	const follow = !!(flags.f || flags.follow);
-	const nFlag = typeof flags.n === "string" ? Number(flags.n) : void 0;
+	const argv = await yargs(rest).usage("Usage: ay read/cat/tail/head <keyword> [options]").option("follow", {
+		alias: "f",
+		type: "boolean",
+		default: false,
+		description: "Follow log output (Ctrl-C to stop)"
+	}).option("n", {
+		type: "number",
+		description: "Number of lines (default: 96 for tail/head)"
+	}).option("all", {
+		type: "boolean",
+		default: false,
+		description: "Include exited agents"
+	}).option("latest", {
+		type: "boolean",
+		default: false,
+		description: "Use most recent match when multiple match"
+	}).option("cwd", {
+		type: "string",
+		description: "Restrict to agents under this dir"
+	}).help(false).version(false).exitProcess(false).parseAsync();
+	const opts = {
+		all: argv.all,
+		active: false,
+		json: false,
+		latest: argv.latest,
+		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
+	};
+	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	const follow = argv.follow;
+	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);
 	const logPath = record.log_file;
@@ -512,12 +529,33 @@ function extractActivityFromLines(lines) {
 	return null;
 }
 async function cmdSend(rest) {
-	const { flags, positional } = parseArgs(rest);
-	const opts = commonOpts(flags);
-	const keyword = positional[0];
-	const rawMessage = positional.slice(1).join(" ");
+	const argv = await yargs(rest).usage("Usage: ay send <keyword> <msg|-> [options]").option("code", {
+		type: "string",
+		default: "enter",
+		description: "Trailing control code (enter|esc|ctrl-c|ctrl-y|tab|none)"
+	}).option("all", {
+		type: "boolean",
+		default: false,
+		description: "Include exited agents"
+	}).option("latest", {
+		type: "boolean",
+		default: false,
+		description: "Use most recent match"
+	}).option("cwd", {
+		type: "string",
+		description: "Restrict to agents under this dir"
+	}).help(false).version(false).exitProcess(false).parseAsync();
+	const opts = {
+		all: argv.all,
+		active: false,
+		json: false,
+		latest: argv.latest,
+		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
+	};
+	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	const rawMessage = argv._.slice(1).map(String).join(" ");
 	if (!keyword) throw new Error("usage: ay send <keyword> <msg|-> [--code=enter|esc|ctrl-c|ctrl-y|tab|none]");
-	const trailing = controlCodeFromName(typeof flags.code === "string" ? flags.code.toLowerCase() : "enter");
+	const trailing = controlCodeFromName(argv.code.toLowerCase());
 	const record = await resolveOne(keyword, opts);
 	const fifoPath = record.fifo_file;
 	if (!fifoPath) throw new Error(`pid ${record.pid}: no fifo_file recorded — agent was not started with --stdpush (or was spawned by Rust which doesn't yet support FIFO IPC; see ROADMAP item 10)`);
@@ -594,13 +632,22 @@ async function writeToIpc(ipcPath, payload) {
 	}
 }
 async function cmdRestart(rest) {
-	const { flags, positional } = parseArgs(rest);
+	const argv = await yargs(rest).usage("Usage: ay restart <keyword>").option("latest", {
+		type: "boolean",
+		default: false,
+		description: "Use most recent match"
+	}).option("cwd", {
+		type: "string",
+		description: "Restrict to agents under this dir"
+	}).help(false).version(false).exitProcess(false).parseAsync();
 	const opts = {
-		...commonOpts(flags),
-		all: true
+		all: true,
+		active: false,
+		json: false,
+		latest: argv.latest,
+		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
 	};
-	const keyword = positional[0];
-	const record = await resolveOne(keyword, opts);
+	const record = await resolveOne(argv._[0] !== void 0 ? String(argv._[0]) : void 0, opts);
 	if (isPidAlive(record.pid)) {
 		process.stderr.write(`pid ${record.pid} is still running — stop it first or use ay send\n`);
 		return 1;
@@ -621,14 +668,16 @@ async function cmdRestart(rest) {
 	return 0;
 }
 async function cmdNote(rest) {
-	const { flags, positional } = parseArgs(rest);
-	const opts = commonOpts(flags);
-	const keyword = positional[0];
-	const note = positional.slice(1).join(" ");
+	const argv = await yargs(rest).usage("Usage: ay note <keyword> [\"note text\"]").help(false).version(false).exitProcess(false).parseAsync();
+	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	const note = argv._.slice(1).map(String).join(" ");
 	if (!keyword) throw new Error("usage: ay note <keyword> [\"note text\"]  (omit text to clear)");
 	const record = await resolveOne(keyword, {
-		...opts,
-		all: true
+		all: true,
+		active: false,
+		json: false,
+		latest: false,
+		cwdScope: null
 	});
 	if (!note) {
 		await writeNote(record.pid, "");
@@ -668,15 +717,34 @@ async function snapshotStatus(record) {
 	};
 }
 async function cmdStatus(rest) {
-	const { flags, positional } = parseArgs(rest);
+	const argv = await yargs(rest).usage("Usage: ay status <keyword> [options]").option("watch", {
+		alias: "w",
+		type: "boolean",
+		default: false,
+		description: "Stream changes as JSON"
+	}).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"
+	}).help(false).version(false).exitProcess(false).parseAsync();
 	const opts = {
-		...commonOpts(flags),
-		all: true
+		all: true,
+		active: false,
+		json: false,
+		latest: argv.latest,
+		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
 	};
-	const keyword = positional[0];
+	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
 	if (!keyword) throw new Error("usage: ay status <keyword> [--watch] [--interval=N]");
-	const watch = !!(flags.watch || flags.w);
-	const intervalFlag = typeof flags.interval === "string" ? Number(flags.interval) : 2;
+	const watch = argv.watch;
+	const intervalFlag = argv.interval;
 	const intervalMs = Math.max(500, (Number.isFinite(intervalFlag) ? intervalFlag : 2) * 1e3);
 	const record = await resolveOne(keyword, opts);
 	const emit = (snap, ts) => {
@@ -716,4 +784,4 @@ async function cmdStatus(rest) {
 
 //#endregion
 export { isSubcommand, runSubcommand };
-//# sourceMappingURL=subcommands-DjO8lthH.js.map
+//# sourceMappingURL=subcommands-BwWcA9uo.js.map

package/dist/{ts-Bw6gQKyU.js → ts-BTCVz_nZ.js}

@@ -1,5 +1,5 @@
 import { n as logger, t as addTransport } from "./logger-B9h0djqx.js";
-import { r as getInstalledPackage } from "./versionChecker-CspuhOwO.js";
+import { r as getInstalledPackage } from "./versionChecker-Cir2ZoFL.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-Bw6gQKyU.js.map
+//# sourceMappingURL=ts-BTCVz_nZ.js.map

package/dist/{versionChecker-CspuhOwO.js → versionChecker-Cir2ZoFL.js}

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 
 //#region package.json
 var name = "claude-yes";
-var version = "1.84.0";
+var version = "1.85.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-CspuhOwO.js.map
+//# sourceMappingURL=versionChecker-Cir2ZoFL.js.map

package/package.json

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

package/ts/subcommands.spec.ts

@@ -27,41 +27,6 @@ async function loadModule() {
   return await import("./subcommands.ts");
 }
 
-describe("subcommands.parseArgs", () => {
-  it("collects positional args and bare flags", async () => {
-    const { parseArgs } = await loadModule();
-    const out = parseArgs(["foo", "bar", "--all"]);
-    expect(out.positional).toEqual(["foo", "bar"]);
-    expect(out.flags.all).toBe(true);
-  });
-
-  it("parses --key=value form", async () => {
-    const { parseArgs } = await loadModule();
-    const out = parseArgs(["--code=enter"]);
-    expect(out.flags.code).toBe("enter");
-  });
-
-  it("parses --key value form for non-boolean keys", async () => {
-    const { parseArgs } = await loadModule();
-    const out = parseArgs(["--cwd", "/tmp/foo"]);
-    expect(out.flags.cwd).toBe("/tmp/foo");
-  });
-
-  it("treats well-known boolean flags as boolean even with a following positional", async () => {
-    const { parseArgs } = await loadModule();
-    const out = parseArgs(["--all", "claude"]);
-    expect(out.flags.all).toBe(true);
-    expect(out.positional).toEqual(["claude"]);
-  });
-
-  it("supports -n N short form", async () => {
-    const { parseArgs } = await loadModule();
-    const out = parseArgs(["-n", "50", "keyword"]);
-    expect(out.flags.n).toBe("50");
-    expect(out.positional).toEqual(["keyword"]);
-  });
-});
-
 describe("subcommands.controlCodeFromName", () => {
   it("maps named codes to the right control bytes", async () => {
     const { controlCodeFromName } = await loadModule();
@@ -525,6 +490,484 @@ describe("subcommands.cmdSend writes bytes to FIFO", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// cmdLs additional arg coverage
+// ---------------------------------------------------------------------------
+
+describe("subcommands.cmdLs -h / --help", () => {
+  function captureStdout() {
+    const chunks: string[] = [];
+    const orig = process.stdout.write.bind(process.stdout);
+    (process.stdout as any).write = (s: any) => {
+      chunks.push(String(s));
+      return true;
+    };
+    return {
+      get text() {
+        return chunks.join("");
+      },
+      restore() {
+        process.stdout.write = orig;
+      },
+    };
+  }
+
+  it("ay ls -h prints usage to stdout and exits 0", async () => {
+    const { runSubcommand } = await loadModule();
+    const cap = captureStdout();
+    let code: number | null;
+    try {
+      code = await runSubcommand(["bun", "cli.js", "ls", "-h"]);
+    } finally {
+      cap.restore();
+    }
+    expect(code).toBe(0);
+    expect(cap.text).toMatch(/Usage:/);
+    expect(cap.text).toMatch(/--all/);
+    expect(cap.text).toMatch(/--json/);
+  });
+
+  it("ay ls --help prints usage to stdout and exits 0", async () => {
+    const { runSubcommand } = await loadModule();
+    const cap = captureStdout();
+    let code: number | null;
+    try {
+      code = await runSubcommand(["bun", "cli.js", "ls", "--help"]);
+    } finally {
+      cap.restore();
+    }
+    expect(code).toBe(0);
+    expect(cap.text).toMatch(/Usage:/);
+  });
+});
+
+describe("subcommands.cmdLs --all / --active / keyword filter / aliases", () => {
+  function captureOutput() {
+    const out: string[] = [];
+    const err: string[] = [];
+    const origOut = process.stdout.write.bind(process.stdout);
+    const origErr = process.stderr.write.bind(process.stderr);
+    (process.stdout as any).write = (s: any) => {
+      out.push(String(s));
+      return true;
+    };
+    (process.stderr as any).write = (s: any) => {
+      err.push(String(s));
+      return true;
+    };
+    return {
+      get stdout() {
+        return out.join("");
+      },
+      get stderr() {
+        return err.join("");
+      },
+      restore() {
+        process.stdout.write = origOut;
+        process.stderr.write = origErr;
+      },
+    };
+  }
+
+  it("--all shows exited agents", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    await appendGlobalPid({
+      pid: 1, // pid 1 is almost never the test process, so isPidAlive returns false
+      cli: "claude",
+      prompt: "exited agent",
+      cwd: process.cwd(),
+      log_file: null,
+      status: "exited",
+      exit_code: 0,
+      exit_reason: "done",
+      started_at: Date.now() - 10_000,
+    });
+
+    const cap = captureOutput();
+    let code: number | null;
+    try {
+      code = await mod.runSubcommand(["bun", "cli.js", "ls", "--all", "--json"]);
+    } finally {
+      cap.restore();
+    }
+    expect(code).toBe(0);
+    const parsed = JSON.parse(cap.stdout);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.some((r: any) => r.prompt === "exited agent")).toBe(true);
+  });
+
+  it("keyword filter restricts results to matching agents", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "unique-xyzzy-prompt",
+      cwd: process.cwd(),
+      log_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+    });
+
+    const cap = captureOutput();
+    let code: number | null;
+    try {
+      code = await mod.runSubcommand(["bun", "cli.js", "ls", "--json", "unique-xyzzy-prompt"]);
+    } finally {
+      cap.restore();
+    }
+    expect(code).toBe(0);
+    const parsed = JSON.parse(cap.stdout);
+    expect(parsed.every((r: any) => r.prompt?.includes("unique-xyzzy-prompt"))).toBe(true);
+  });
+
+  it("keyword filter returns 'no running agents' when nothing matches", async () => {
+    const { runSubcommand } = await loadModule();
+    const stderr: string[] = [];
+    const orig = process.stderr.write.bind(process.stderr);
+    (process.stderr as any).write = (s: any) => {
+      stderr.push(String(s));
+      return true;
+    };
+    try {
+      const code = await runSubcommand(["bun", "cli.js", "ls", "no-match-zzzzzz"]);
+      expect(code).toBe(0);
+      expect(stderr.join("")).toMatch(/no running agents matched/);
+    } finally {
+      process.stderr.write = orig;
+    }
+  });
+
+  it("list alias routes to cmdLs", async () => {
+    const { runSubcommand } = await loadModule();
+    const stderr: string[] = [];
+    const orig = process.stderr.write.bind(process.stderr);
+    (process.stderr as any).write = (s: any) => {
+      stderr.push(String(s));
+      return true;
+    };
+    try {
+      const code = await runSubcommand(["bun", "cli.js", "list"]);
+      expect(code).toBe(0);
+    } finally {
+      process.stderr.write = orig;
+    }
+  });
+
+  it("ps alias routes to cmdLs", async () => {
+    const { runSubcommand } = await loadModule();
+    const stderr: string[] = [];
+    const orig = process.stderr.write.bind(process.stderr);
+    (process.stderr as any).write = (s: any) => {
+      stderr.push(String(s));
+      return true;
+    };
+    try {
+      const code = await runSubcommand(["bun", "cli.js", "ps"]);
+      expect(code).toBe(0);
+    } finally {
+      process.stderr.write = orig;
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// cmdRead — head and cat modes
+// ---------------------------------------------------------------------------
+
+describe("subcommands.cmdRead head and cat modes", () => {
+  it("head emits first N lines", async () => {
+    const { runSubcommand } = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const tmp = await mkdtemp(path.join(tmpdir(), "ay-head-log-"));
+    try {
+      const logPath = path.join(tmp, "x.raw.log");
+      const lines: string[] = [];
+      for (let i = 0; i < 50; i++) lines.push(`line-${i}`);
+      await writeFile(logPath, lines.join("\r\n") + "\r\n");
+
+      await appendGlobalPid({
+        pid: process.pid,
+        cli: "claude",
+        prompt: null,
+        cwd: process.cwd(),
+        log_file: logPath,
+        status: "active",
+        exit_code: null,
+        exit_reason: null,
+        started_at: Date.now(),
+      });
+
+      const stdout: string[] = [];
+      const orig = process.stdout.write.bind(process.stdout);
+      (process.stdout as any).write = (s: any) => {
+        stdout.push(String(s));
+        return true;
+      };
+      const stderr_chunks: string[] = [];
+      const origErr = process.stderr.write.bind(process.stderr);
+      (process.stderr as any).write = (s: any) => {
+        stderr_chunks.push(String(s));
+        return true;
+      };
+      try {
+        const code = await runSubcommand(["bun", "cli.js", "head", String(process.pid), "-n", "5"]);
+        expect(code).toBe(0);
+      } finally {
+        process.stdout.write = orig;
+        process.stderr.write = origErr;
+      }
+      const text = stdout.join("");
+      expect(text).toMatch(/line-0/);
+      expect(text).toMatch(/line-4/);
+      expect(text).not.toMatch(/line-10\b/);
+    } finally {
+      await rm(tmp, { recursive: true, force: true }).catch(() => null);
+    }
+  });
+
+  it("cat emits all lines", async () => {
+    const { runSubcommand } = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const tmp = await mkdtemp(path.join(tmpdir(), "ay-cat-log-"));
+    try {
+      const logPath = path.join(tmp, "x.raw.log");
+      await writeFile(logPath, "alpha\r\nbeta\r\ngamma\r\n");
+
+      await appendGlobalPid({
+        pid: process.pid,
+        cli: "claude",
+        prompt: null,
+        cwd: process.cwd(),
+        log_file: logPath,
+        status: "active",
+        exit_code: null,
+        exit_reason: null,
+        started_at: Date.now(),
+      });
+
+      const stdout: string[] = [];
+      const orig = process.stdout.write.bind(process.stdout);
+      (process.stdout as any).write = (s: any) => {
+        stdout.push(String(s));
+        return true;
+      };
+      const stderr_chunks: string[] = [];
+      const origErr = process.stderr.write.bind(process.stderr);
+      (process.stderr as any).write = (s: any) => {
+        stderr_chunks.push(String(s));
+        return true;
+      };
+      try {
+        const code = await runSubcommand(["bun", "cli.js", "cat", String(process.pid)]);
+        expect(code).toBe(0);
+      } finally {
+        process.stdout.write = orig;
+        process.stderr.write = origErr;
+      }
+      const text = stdout.join("");
+      expect(text).toMatch(/alpha/);
+      expect(text).toMatch(/beta/);
+      expect(text).toMatch(/gamma/);
+    } finally {
+      await rm(tmp, { recursive: true, force: true }).catch(() => null);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// cmdNote
+// ---------------------------------------------------------------------------
+
+describe("subcommands.cmdNote", () => {
+  it("throws usage error when no keyword given", async () => {
+    const { runSubcommand } = await loadModule();
+    const stderr: string[] = [];
+    const orig = process.stderr.write.bind(process.stderr);
+    (process.stderr as any).write = (s: any) => {
+      stderr.push(String(s));
+      return true;
+    };
+    try {
+      const code = await runSubcommand(["bun", "cli.js", "note"]);
+      expect(code).toBe(1);
+      expect(stderr.join("")).toMatch(/usage:/i);
+    } finally {
+      process.stderr.write = orig;
+    }
+  });
+
+  it("sets a note on a matched agent", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "note-target",
+      cwd: process.cwd(),
+      log_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+    });
+
+    const stdout: string[] = [];
+    const origOut = process.stdout.write.bind(process.stdout);
+    (process.stdout as any).write = (s: any) => {
+      stdout.push(String(s));
+      return true;
+    };
+    const origErr = process.stderr.write.bind(process.stderr);
+    (process.stderr as any).write = () => true;
+    try {
+      const code = await mod.runSubcommand([
+        "bun",
+        "cli.js",
+        "note",
+        String(process.pid),
+        "my note text",
+      ]);
+      expect(code).toBe(0);
+      expect(stdout.join("")).toMatch(/note set/);
+    } finally {
+      process.stdout.write = origOut;
+      process.stderr.write = origErr;
+    }
+  });
+
+  it("clears a note when no text given", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "note-clear-target",
+      cwd: process.cwd(),
+      log_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+    });
+
+    const stdout: string[] = [];
+    const origOut = process.stdout.write.bind(process.stdout);
+    (process.stdout as any).write = (s: any) => {
+      stdout.push(String(s));
+      return true;
+    };
+    (process.stderr as any).write = () => true;
+    try {
+      const code = await mod.runSubcommand(["bun", "cli.js", "note", String(process.pid)]);
+      expect(code).toBe(0);
+      expect(stdout.join("")).toMatch(/cleared note/);
+    } finally {
+      process.stdout.write = origOut;
+      process.stderr.write = process.stderr.write; // no-op restore (silenced above)
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// cmdStatus
+// ---------------------------------------------------------------------------
+
+describe("subcommands.cmdStatus", () => {
+  it("throws usage error when no keyword given", async () => {
+    const { runSubcommand } = await loadModule();
+    const stderr: string[] = [];
+    const orig = process.stderr.write.bind(process.stderr);
+    (process.stderr as any).write = (s: any) => {
+      stderr.push(String(s));
+      return true;
+    };
+    try {
+      const code = await runSubcommand(["bun", "cli.js", "status"]);
+      expect(code).toBe(1);
+      expect(stderr.join("")).toMatch(/usage:/i);
+    } finally {
+      process.stderr.write = orig;
+    }
+  });
+
+  it("emits JSON snapshot for a matched agent", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "status-test",
+      cwd: process.cwd(),
+      log_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now() - 1000,
+    });
+
+    const stdout: string[] = [];
+    const origOut = process.stdout.write.bind(process.stdout);
+    (process.stdout as any).write = (s: any) => {
+      stdout.push(String(s));
+      return true;
+    };
+    (process.stderr as any).write = () => true;
+    try {
+      const code = await mod.runSubcommand(["bun", "cli.js", "status", String(process.pid)]);
+      expect(code).toBe(0);
+    } finally {
+      process.stdout.write = origOut;
+    }
+    const snap = JSON.parse(stdout.join(""));
+    expect(snap).toMatchObject({ pid: process.pid, cli: "claude" });
+    expect(typeof snap.age_ms).toBe("number");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// cmdRestart
+// ---------------------------------------------------------------------------
+
+describe("subcommands.cmdRestart", () => {
+  it("returns 1 and warns when the agent is still alive", async () => {
+    const mod = await loadModule();
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "restart-live-test",
+      cwd: process.cwd(),
+      log_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+    });
+
+    const stderr: string[] = [];
+    const origErr = process.stderr.write.bind(process.stderr);
+    (process.stderr as any).write = (s: any) => {
+      stderr.push(String(s));
+      return true;
+    };
+    try {
+      const code = await mod.runSubcommand(["bun", "cli.js", "restart", String(process.pid)]);
+      expect(code).toBe(1);
+      expect(stderr.join("")).toMatch(/still running/);
+    } finally {
+      process.stderr.write = origErr;
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listRecords merges per-cwd TS file with global
+// ---------------------------------------------------------------------------
+
 describe("subcommands.listRecords merges per-cwd TS file with global", () => {
   it("includes records from <cwd>/.agent-yes/pid-records.jsonl", async () => {
     // Write a fake per-cwd file that uses the live process pid so liveOnly

package/ts/subcommands.ts

@@ -15,6 +15,7 @@ import { appendFile, mkdir, open, readFile, stat, writeFile } from "fs/promises"
 import { homedir } from "os";
 import path from "path";
 import { type GlobalPidRecord, readGlobalPids } from "./globalPidIndex.ts";
+import yargs from "yargs";
 
 // ---------------------------------------------------------------------------
 // notes store  (~/.agent-yes/notes.jsonl)
@@ -196,65 +197,6 @@ interface CommonOpts {
   json: boolean;
 }
 
-interface ParsedArgs {
-  flags: Record<string, string | boolean>;
-  positional: string[];
-}
-
-export function parseArgs(rest: string[]): ParsedArgs {
-  const flags: Record<string, string | boolean> = {};
-  const positional: string[] = [];
-  for (let i = 0; i < rest.length; i++) {
-    const arg = rest[i]!;
-    if (arg.startsWith("--")) {
-      const eq = arg.indexOf("=");
-      if (eq >= 0) {
-        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
-      } else {
-        const key = arg.slice(2);
-        const next = rest[i + 1];
-        // Boolean flags: --all, --json, --latest
-        if (
-          ["all", "active", "follow", "json", "latest", "watch"].includes(key) ||
-          !next ||
-          next.startsWith("-")
-        ) {
-          flags[key] = true;
-        } else {
-          flags[key] = next;
-          i++;
-        }
-      }
-    } else if (arg.startsWith("-") && arg.length > 1) {
-      // -n N short flag
-      if (arg === "-n") {
-        flags["n"] = rest[i + 1] ?? "";
-        i++;
-      } else {
-        flags[arg.slice(1)] = true;
-      }
-    } else {
-      positional.push(arg);
-    }
-  }
-  return { flags, positional };
-}
-
-function commonOpts(flags: Record<string, string | boolean>): CommonOpts {
-  return {
-    all: !!flags.all,
-    active: !!flags.active,
-    cwdScope:
-      typeof flags.cwd === "string"
-        ? path.resolve(flags.cwd)
-        : flags.cwd === true
-          ? process.cwd()
-          : null,
-    latest: !!flags.latest,
-    json: !!flags.json,
-  };
-}
-
 export function matchKeyword(record: GlobalPidRecord, keyword: string): boolean {
   if (!keyword) return true;
   const kw = keyword.toLowerCase();
@@ -331,9 +273,54 @@ async function resolveOne(keyword: string | undefined, opts: CommonOpts): Promis
 // ---------------------------------------------------------------------------
 
 async function cmdLs(rest: string[]): Promise<number> {
-  const { flags, positional } = parseArgs(rest);
-  const opts = commonOpts(flags);
-  const keyword = positional[0];
+  const y = yargs(rest)
+    .usage(
+      "Usage: ay ls [keyword] [options]\n" +
+        "       ay list [keyword] [options]\n" +
+        "       ay ps   [keyword] [options]\n\n" +
+        "List running agents. Optionally filter by keyword (pid, cwd substring, or prompt substring).",
+    )
+    .option("all", {
+      type: "boolean",
+      default: false,
+      description: "Show all agents including exited ones",
+    })
+    .option("active", {
+      type: "boolean",
+      default: false,
+      description: "Only show agents with an alive process",
+    })
+    .option("json", { type: "boolean", default: false, description: "Output as JSON array" })
+    .option("latest", {
+      type: "boolean",
+      default: false,
+      description: "Show only the most recent agent",
+    })
+    .option("cwd", { type: "string", description: "Restrict to agents whose cwd starts with dir" })
+    .option("help", { alias: "h", type: "boolean", default: false, description: "Show this help" })
+    .example("ay ls", "list running agents")
+    .example("ay ls --all", "include exited agents")
+    .example("ay ls --json", "machine-readable output")
+    .example("ay ls symval", "filter by cwd/prompt keyword")
+    .help(false)
+    .version(false)
+    .exitProcess(false);
+
+  const argv = await y.parseAsync();
+
+  if (argv.help || argv.h) {
+    process.stdout.write((await y.getHelp()) + "\n");
+    return 0;
+  }
+
+  const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
+  const opts: CommonOpts = {
+    all: argv.all,
+    active: argv.active,
+    json: argv.json,
+    latest: argv.latest,
+    cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null,
+  };
   const records = await listRecords(keyword, opts);
 
   if (opts.json) {
@@ -488,12 +475,37 @@ interface ReadOpts {
 }
 
 async function cmdRead(rest: string[], { mode }: ReadOpts): Promise<number> {
-  const { flags, positional } = parseArgs(rest);
-  const opts = commonOpts(flags);
-  const keyword = positional[0];
-  const follow = !!(flags.f || flags.follow);
-
-  const nFlag = typeof flags.n === "string" ? Number(flags.n) : undefined;
+  const y = yargs(rest)
+    .usage("Usage: ay read/cat/tail/head <keyword> [options]")
+    .option("follow", {
+      alias: "f",
+      type: "boolean",
+      default: false,
+      description: "Follow log output (Ctrl-C to stop)",
+    })
+    .option("n", { type: "number", description: "Number of lines (default: 96 for tail/head)" })
+    .option("all", { type: "boolean", default: false, description: "Include exited agents" })
+    .option("latest", {
+      type: "boolean",
+      default: false,
+      description: "Use most recent match when multiple match",
+    })
+    .option("cwd", { type: "string", description: "Restrict to agents under this dir" })
+    .help(false)
+    .version(false)
+    .exitProcess(false);
+
+  const argv = await y.parseAsync();
+  const opts: CommonOpts = {
+    all: argv.all,
+    active: false,
+    json: false,
+    latest: argv.latest,
+    cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null,
+  };
+  const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
+  const follow = argv.follow;
+  const nFlag = argv.n;
   const n =
     nFlag !== undefined && Number.isFinite(nFlag) && nFlag > 0
       ? Math.floor(nFlag)
@@ -732,15 +744,35 @@ function extractActivityFromLines(lines: string[]): string | null {
 // ---------------------------------------------------------------------------
 
 async function cmdSend(rest: string[]): Promise<number> {
-  const { flags, positional } = parseArgs(rest);
-  const opts = commonOpts(flags);
-  const keyword = positional[0];
-  const rawMessage = positional.slice(1).join(" ");
+  const y = yargs(rest)
+    .usage("Usage: ay send <keyword> <msg|-> [options]")
+    .option("code", {
+      type: "string",
+      default: "enter",
+      description: "Trailing control code (enter|esc|ctrl-c|ctrl-y|tab|none)",
+    })
+    .option("all", { type: "boolean", default: false, description: "Include exited agents" })
+    .option("latest", { type: "boolean", default: false, description: "Use most recent match" })
+    .option("cwd", { type: "string", description: "Restrict to agents under this dir" })
+    .help(false)
+    .version(false)
+    .exitProcess(false);
+
+  const argv = await y.parseAsync();
+  const opts: CommonOpts = {
+    all: argv.all,
+    active: false,
+    json: false,
+    latest: argv.latest,
+    cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null,
+  };
+  const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
+  const rawMessage = argv._.slice(1).map(String).join(" ");
 
   if (!keyword)
     throw new Error("usage: ay send <keyword> <msg|-> [--code=enter|esc|ctrl-c|ctrl-y|tab|none]");
 
-  const codeName = typeof flags.code === "string" ? flags.code.toLowerCase() : "enter";
+  const codeName = argv.code.toLowerCase();
   const trailing = controlCodeFromName(codeName);
 
   const record = await resolveOne(keyword, opts);
@@ -855,9 +887,23 @@ async function writeToIpc(ipcPath: string, payload: string): Promise<void> {
 // ---------------------------------------------------------------------------
 
 async function cmdRestart(rest: string[]): Promise<number> {
-  const { flags, positional } = parseArgs(rest);
-  const opts = { ...commonOpts(flags), all: true }; // search stopped agents too
-  const keyword = positional[0];
+  const y = yargs(rest)
+    .usage("Usage: ay restart <keyword>")
+    .option("latest", { type: "boolean", default: false, description: "Use most recent match" })
+    .option("cwd", { type: "string", description: "Restrict to agents under this dir" })
+    .help(false)
+    .version(false)
+    .exitProcess(false);
+
+  const argv = await y.parseAsync();
+  const opts: CommonOpts = {
+    all: true,
+    active: false,
+    json: false,
+    latest: argv.latest,
+    cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null,
+  };
+  const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
   const record = await resolveOne(keyword, opts);
 
   if (isPidAlive(record.pid)) {
@@ -890,14 +936,25 @@ async function cmdRestart(rest: string[]): Promise<number> {
 // ---------------------------------------------------------------------------
 
 async function cmdNote(rest: string[]): Promise<number> {
-  const { flags, positional } = parseArgs(rest);
-  const opts = commonOpts(flags);
-  const keyword = positional[0];
-  const note = positional.slice(1).join(" ");
+  const y = yargs(rest)
+    .usage('Usage: ay note <keyword> ["note text"]')
+    .help(false)
+    .version(false)
+    .exitProcess(false);
+
+  const argv = await y.parseAsync();
+  const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
+  const note = argv._.slice(1).map(String).join(" ");
 
   if (!keyword) throw new Error('usage: ay note <keyword> ["note text"]  (omit text to clear)');
 
-  const record = await resolveOne(keyword, { ...opts, all: true });
+  const record = await resolveOne(keyword, {
+    all: true,
+    active: false,
+    json: false,
+    latest: false,
+    cwdScope: null,
+  });
 
   if (!note) {
     // clear
@@ -967,14 +1024,35 @@ async function snapshotStatus(record: GlobalPidRecord): Promise<StatusSnapshot>
 }
 
 async function cmdStatus(rest: string[]): Promise<number> {
-  const { flags, positional } = parseArgs(rest);
-  const opts = { ...commonOpts(flags), all: true };
-  const keyword = positional[0];
+  const y = yargs(rest)
+    .usage("Usage: ay status <keyword> [options]")
+    .option("watch", {
+      alias: "w",
+      type: "boolean",
+      default: false,
+      description: "Stream changes as JSON",
+    })
+    .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" })
+    .help(false)
+    .version(false)
+    .exitProcess(false);
+
+  const argv = await y.parseAsync();
+  const opts: CommonOpts = {
+    all: true,
+    active: false,
+    json: false,
+    latest: argv.latest,
+    cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null,
+  };
+  const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
 
   if (!keyword) throw new Error("usage: ay status <keyword> [--watch] [--interval=N]");
 
-  const watch = !!(flags.watch || flags.w);
-  const intervalFlag = typeof flags.interval === "string" ? Number(flags.interval) : 2;
+  const watch = argv.watch;
+  const intervalFlag = argv.interval;
   const intervalMs = Math.max(500, (Number.isFinite(intervalFlag) ? intervalFlag : 2) * 1000);
 
   const record = await resolveOne(keyword, opts);