agent-yes 1.84.0 → 1.86.0

package/ts/subcommands.ts

@@ -15,6 +15,8 @@ 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";
+import { type ResolvedRemote, readRemotes, resolveRemoteSpec } from "./remotes.ts";
 
 // ---------------------------------------------------------------------------
 // notes store  (~/.agent-yes/notes.jsonl)
@@ -25,7 +27,7 @@ function notesPath(): string {
   return path.join(dir, "notes.jsonl");
 }
 
-async function readNotes(): Promise<Map<number, string>> {
+export async function readNotes(): Promise<Map<number, string>> {
   let raw: string;
   try {
     raw = await readFile(notesPath(), "utf-8");
@@ -135,6 +137,8 @@ const SUBCOMMANDS = new Set([
   "send",
   "restart",
   "note",
+  "serve",
+  "remote",
 ]);
 
 const IDLE_THRESHOLD_MS = 60 * 1000;
@@ -174,6 +178,14 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
         return await cmdRestart(rest);
       case "note":
         return await cmdNote(rest);
+      case "serve": {
+        const { cmdServe } = await import("./serve.ts");
+        return cmdServe(rest);
+      }
+      case "remote": {
+        const { cmdRemote } = await import("./remotes.ts");
+        return cmdRemote(rest);
+      }
       default:
         return null;
     }
@@ -188,7 +200,7 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
 // shared helpers
 // ---------------------------------------------------------------------------
 
-interface CommonOpts {
+export interface CommonOpts {
   all: boolean;
   active: boolean;
   cwdScope: string | null;
@@ -196,65 +208,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();
@@ -269,7 +222,7 @@ export function matchKeyword(record: GlobalPidRecord, keyword: string): boolean
   return false;
 }
 
-async function listRecords(
+export async function listRecords(
   keyword: string | undefined,
   opts: CommonOpts,
 ): Promise<GlobalPidRecord[]> {
@@ -298,7 +251,7 @@ async function listRecords(
   return records;
 }
 
-function isPidAlive(pid: number): boolean {
+export function isPidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
     return true;
@@ -307,7 +260,10 @@ function isPidAlive(pid: number): boolean {
   }
 }
 
-async function resolveOne(keyword: string | undefined, opts: CommonOpts): Promise<GlobalPidRecord> {
+export async function resolveOne(
+  keyword: string | undefined,
+  opts: CommonOpts,
+): Promise<GlobalPidRecord> {
   if (!keyword) {
     throw new Error("keyword required (pid, cwd substring, cli name, or prompt substring)");
   }
@@ -326,14 +282,390 @@ async function resolveOne(keyword: string | undefined, opts: CommonOpts): Promis
   );
 }
 
+// ---------------------------------------------------------------------------
+// remote routing helpers
+// ---------------------------------------------------------------------------
+
+async function remoteGet(remote: ResolvedRemote, pathname: string): Promise<Response> {
+  return fetch(`${remote.url}${pathname}`, {
+    headers: { Authorization: `Bearer ${remote.token}` },
+  });
+}
+
+async function remotePost(
+  remote: ResolvedRemote,
+  pathname: string,
+  body: unknown,
+): Promise<Response> {
+  return fetch(`${remote.url}${pathname}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${remote.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+async function runRemoteLs(
+  remote: ResolvedRemote,
+  opts: { all: boolean; active: boolean },
+): Promise<number> {
+  const params = new URLSearchParams();
+  if (remote.keyword) params.set("keyword", remote.keyword);
+  if (opts.all) params.set("all", "1");
+  if (opts.active) params.set("active", "1");
+  const res = await remoteGet(remote, `/api/ls?${params}`);
+  if (!res.ok) {
+    process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+    return 1;
+  }
+  const records = (await res.json()) as any[];
+  if (records.length === 0) {
+    process.stderr.write(
+      remote.keyword
+        ? `no agents matched "${remote.keyword}" on ${remote.url}\n`
+        : `no running agents on ${remote.url}\n`,
+    );
+    return 0;
+  }
+  process.stderr.write(`[remote ${remote.url}]\n`);
+  const termWidth = (process.stdout as any).columns ?? 120;
+  const widths = {
+    pid: Math.max(3, ...records.map((r: any) => String(r.pid).length)),
+    cli: Math.max(3, ...records.map((r: any) => String(r.cli).length)),
+    status: Math.max(6, ...records.map((r: any) => String(r.status).length)),
+    cwd: Math.max(3, ...records.map((r: any) => String(r.cwd).length)),
+  };
+  const fixedWidth = widths.pid + widths.cli + widths.status + widths.cwd + 4 * 2;
+  const promptBudget = Math.max(20, termWidth - fixedWidth - 1);
+  const header =
+    [
+      "PID".padEnd(widths.pid),
+      "CLI".padEnd(widths.cli),
+      "STATUS".padEnd(widths.status),
+      "CWD".padEnd(widths.cwd),
+      "PROMPT",
+    ].join("  ") + "\n";
+  process.stdout.write(header);
+  for (const r of records) {
+    const label = r.prompt ? truncate(`→ ${r.prompt}`, promptBudget) : "";
+    process.stdout.write(
+      [
+        String(r.pid).padEnd(widths.pid),
+        String(r.cli).padEnd(widths.cli),
+        String(r.status).padEnd(widths.status),
+        String(r.cwd).padEnd(widths.cwd),
+        label,
+      ].join("  ") + "\n",
+    );
+  }
+  return 0;
+}
+
+async function runRemoteRead(
+  remote: ResolvedRemote,
+  mode: "cat" | "tail" | "head",
+  follow: boolean,
+  n: number,
+  reconnectTimeoutMs = 120_000,
+): Promise<number> {
+  const keyword = remote.keyword ?? "";
+  if (!keyword) {
+    process.stderr.write(
+      "remote tail/cat/head requires a keyword (e.g. token@host:port:keyword)\n",
+    );
+    return 1;
+  }
+
+  if (mode === "tail" && follow) {
+    const ac = new AbortController();
+    process.on("SIGINT", () => ac.abort());
+    const deadline = Date.now() + reconnectTimeoutMs;
+    let delay = 1_000;
+    let attempt = 0;
+
+    process.stderr.write(
+      `[remote ${remote.url}  ${keyword}]\nfollowing... (Ctrl-C to stop, timeout: ${Math.round(reconnectTimeoutMs / 1000)}s)\n`,
+    );
+
+    while (!ac.signal.aborted) {
+      try {
+        const res = await fetch(`${remote.url}/api/tail/${encodeURIComponent(keyword)}`, {
+          headers: { Authorization: `Bearer ${remote.token}`, Accept: "text/event-stream" },
+          signal: ac.signal,
+        });
+        if (!res.ok) {
+          // 401/404 are permanent failures — no point retrying
+          if (res.status === 401 || res.status === 404) {
+            process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+            return 1;
+          }
+          throw new Error(`HTTP ${res.status}`);
+        }
+
+        if (attempt > 0) process.stderr.write("remote: reconnected\n");
+        delay = 1_000; // reset backoff on successful connect
+
+        const reader = res.body!.getReader();
+        const dec = new TextDecoder();
+        let buf = "";
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          const lines = buf.split("\n");
+          buf = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.startsWith("data: ")) continue;
+            try {
+              const text = JSON.parse(line.slice(6)) as string;
+              process.stdout.write(text);
+              if (!text.endsWith("\n")) process.stdout.write("\n");
+            } catch {
+              /* skip non-JSON */
+            }
+          }
+        }
+        break; // stream ended cleanly
+      } catch (e: any) {
+        if (e.name === "AbortError" || ac.signal.aborted) return 0;
+        if (Date.now() >= deadline) {
+          process.stderr.write(
+            `remote: timeout after ${Math.round(reconnectTimeoutMs / 1000)}s, giving up\n`,
+          );
+          return 1;
+        }
+        process.stderr.write(
+          `remote: disconnected (${e.message}), retrying in ${delay / 1000}s…\n`,
+        );
+        await new Promise<void>((resolve, reject) => {
+          const t = setTimeout(resolve, delay);
+          ac.signal.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(new Error("abort"));
+          });
+        }).catch(() => {});
+        if (ac.signal.aborted) return 0;
+        delay = Math.min(delay * 2, 30_000);
+        attempt++;
+      }
+    }
+    return 0;
+  }
+
+  // Static read (cat/head/tail without -f)
+  const params = new URLSearchParams({ mode, n: String(n) });
+  const res = await remoteGet(remote, `/api/read/${encodeURIComponent(keyword)}?${params}`);
+  if (!res.ok) {
+    process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+    return 1;
+  }
+  const text = await res.text();
+  process.stderr.write(`[remote ${remote.url}  ${keyword}]\n`);
+  process.stdout.write(text);
+  if (!text.endsWith("\n")) process.stdout.write("\n");
+  return 0;
+}
+
+async function runRemoteSend(remote: ResolvedRemote, msg: string, code: string): Promise<number> {
+  const keyword = remote.keyword ?? "";
+  if (!keyword) {
+    process.stderr.write("remote send requires a keyword (e.g. token@host:port:keyword)\n");
+    return 1;
+  }
+  const res = await remotePost(remote, "/api/send", { keyword, msg, code });
+  if (!res.ok) {
+    process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+    return 1;
+  }
+  const data = (await res.json()) as any;
+  process.stdout.write(`sent to remote pid ${data.pid} (${remote.url}  ${keyword})\n`);
+  return 0;
+}
+
+async function runRemoteStatus(remote: ResolvedRemote): Promise<number> {
+  const keyword = remote.keyword ?? "";
+  if (!keyword) {
+    process.stderr.write("remote status requires a keyword (e.g. token@host:port:keyword)\n");
+    return 1;
+  }
+  const res = await remoteGet(remote, `/api/status/${encodeURIComponent(keyword)}`);
+  if (!res.ok) {
+    process.stderr.write(`remote error ${res.status}: ${await res.text()}\n`);
+    return 1;
+  }
+  process.stdout.write(JSON.stringify(await res.json(), null, 2) + "\n");
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// --all-remotes helpers
+// ---------------------------------------------------------------------------
+
+async function fetchRemoteRecordsRaw(
+  url: string,
+  token: string,
+  opts: { all: boolean; active: boolean; keyword?: string },
+): Promise<any[]> {
+  const params = new URLSearchParams();
+  if (opts.all) params.set("all", "1");
+  if (opts.active) params.set("active", "1");
+  if (opts.keyword) params.set("keyword", opts.keyword);
+  try {
+    const res = await fetch(`${url}/api/ls?${params}`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return [];
+    return (await res.json()) as any[];
+  } catch {
+    return [];
+  }
+}
+
+async function runAllRemotesLs(opts: {
+  all: boolean;
+  active: boolean;
+  keyword?: string;
+}): Promise<number> {
+  const remotes = await readRemotes();
+  const localOpts: CommonOpts = {
+    all: opts.all,
+    active: opts.active,
+    json: true,
+    latest: false,
+    cwdScope: null,
+  };
+
+  const [localResult, ...remoteResults] = await Promise.allSettled([
+    listRecords(opts.keyword, localOpts).then((recs) => ({
+      host: "local",
+      records: recs as any[],
+    })),
+    ...Array.from(remotes.entries()).map(([alias, cfg]) =>
+      fetchRemoteRecordsRaw(cfg.url, cfg.token, opts).then((records) => ({ host: alias, records })),
+    ),
+  ]);
+
+  type HostedRow = { host: string; rec: any };
+  const rows: HostedRow[] = [];
+  if (localResult.status === "fulfilled") {
+    for (const r of localResult.value.records) rows.push({ host: "local", rec: r });
+  }
+  for (const res of remoteResults) {
+    if (res.status === "fulfilled") {
+      for (const r of res.value.records) rows.push({ host: res.value.host, rec: r });
+    }
+  }
+
+  if (rows.length === 0) {
+    process.stderr.write("no running agents\n");
+    return 0;
+  }
+
+  const termWidth = (process.stdout as any).columns ?? 120;
+  const hostW = Math.max(4, ...rows.map((r) => r.host.length));
+  const pidW = Math.max(3, ...rows.map((r) => String(r.rec.pid).length));
+  const cliW = Math.max(3, ...rows.map((r) => String(r.rec.cli).length));
+  const statusW = Math.max(6, ...rows.map((r) => String(r.rec.status).length));
+  const cwdW = Math.max(3, ...rows.map((r) => shortenPath(String(r.rec.cwd)).length));
+  const promptBudget = Math.max(20, termWidth - hostW - pidW - cliW - statusW - cwdW - 5 * 2 - 1);
+
+  process.stdout.write(
+    [
+      "HOST".padEnd(hostW),
+      "PID".padEnd(pidW),
+      "CLI".padEnd(cliW),
+      "STATUS".padEnd(statusW),
+      "CWD".padEnd(cwdW),
+      "PROMPT",
+    ].join("  ") + "\n",
+  );
+  for (const { host, rec } of rows) {
+    const label = rec.prompt ? truncate(`→ ${rec.prompt}`, promptBudget) : "";
+    process.stdout.write(
+      [
+        host.padEnd(hostW),
+        String(rec.pid).padEnd(pidW),
+        String(rec.cli).padEnd(cliW),
+        String(rec.status).padEnd(statusW),
+        shortenPath(String(rec.cwd)).padEnd(cwdW),
+        label,
+      ].join("  ") + "\n",
+    );
+  }
+  return 0;
+}
+
 // ---------------------------------------------------------------------------
 // ay ls
 // ---------------------------------------------------------------------------
 
 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("all-remotes", {
+      type: "boolean",
+      default: false,
+      description: "Include agents from all configured remotes (remotes.yaml)",
+    })
+    .option("help", { alias: "h", type: "boolean", default: false, description: "Show this help" })
+    .example("ay ls", "list running agents")
+    .example("ay ls --all-remotes", "include all configured remote machines")
+    .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;
+  }
+
+  if (argv["all-remotes"]) {
+    return runAllRemotesLs({
+      all: argv.all,
+      active: argv.active,
+      keyword: argv._[0] !== undefined ? String(argv._[0]) : undefined,
+    });
+  }
+
+  const keyword = argv._[0] !== undefined ? String(argv._[0]) : undefined;
+  if (keyword) {
+    const remote = await resolveRemoteSpec(keyword);
+    if (remote) return runRemoteLs(remote, { all: argv.all, active: argv.active });
+  }
+  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 +820,54 @@ 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" })
+    .option("reconnect-timeout", {
+      type: "number",
+      default: 120,
+      description: "Seconds before giving up reconnecting remote SSE (default: 120)",
+    })
+    .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;
+  if (keyword) {
+    const remote = await resolveRemoteSpec(keyword);
+    const nFlag2 = argv.n;
+    const n2 =
+      nFlag2 !== undefined && Number.isFinite(nFlag2) && nFlag2 > 0
+        ? Math.floor(nFlag2)
+        : mode === "cat"
+          ? 0
+          : 96;
+    const reconnectTimeoutMs = ((argv["reconnect-timeout"] as number) ?? 120) * 1000;
+    if (remote) return runRemoteRead(remote, mode, argv.follow, n2, reconnectTimeoutMs);
+  }
+  const follow = argv.follow;
+  const nFlag = argv.n;
   const n =
     nFlag !== undefined && Number.isFinite(nFlag) && nFlag > 0
       ? Math.floor(nFlag)
@@ -567,7 +941,7 @@ async function cmdRead(rest: string[], { mode }: ReadOpts): Promise<number> {
  * Feed the raw PTY bytes through @xterm/headless and emit plain text.
  * Same approach as koho's renderTerminalBuffer + agent-yes's XtermProxy.
  */
-async function renderRawLog(
+export async function renderRawLog(
   buf: Uint8Array,
   { mode, n }: { mode: "cat" | "tail" | "head"; n: number },
 ): Promise<string> {
@@ -732,15 +1106,39 @@ 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 remote = await resolveRemoteSpec(keyword);
+    if (remote) return runRemoteSend(remote, rawMessage, codeName);
+  }
   const trailing = controlCodeFromName(codeName);
 
   const record = await resolveOne(keyword, opts);
@@ -819,7 +1217,7 @@ export function controlCodeFromName(name: string): string {
   }
 }
 
-async function writeToIpc(ipcPath: string, payload: string): Promise<void> {
+export async function writeToIpc(ipcPath: string, payload: string): Promise<void> {
   if (process.platform === "win32") {
     const { connect } = await import("net");
     await new Promise<void>((resolve, reject) => {
@@ -855,9 +1253,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 +1302,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
@@ -917,7 +1340,7 @@ async function cmdNote(rest: string[]): Promise<number> {
 // ay status
 // ---------------------------------------------------------------------------
 
-interface StatusSnapshot {
+export interface StatusSnapshot {
   pid: number;
   cli: string;
   cwd: string;
@@ -932,7 +1355,7 @@ interface StatusSnapshot {
   log_file: string | null;
 }
 
-async function snapshotStatus(record: GlobalPidRecord): Promise<StatusSnapshot> {
+export async function snapshotStatus(record: GlobalPidRecord): Promise<StatusSnapshot> {
   const alive = isPidAlive(record.pid);
   let state: "active" | "idle" | "stopped";
   let logMtimeMs: number | null = null;
@@ -967,14 +1390,40 @@ 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 remote = await resolveRemoteSpec(keyword);
+    if (remote) return runRemoteStatus(remote);
+  }
+
+  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);