claude-yes 1.89.0 → 1.90.1

package/README.md

@@ -142,8 +142,18 @@ cy tail <keyword>                      # render last 96 lines via @xterm/headles
 cy read <keyword>                      # full rendered log
 cy send <keyword> "next: run tests"    # append a prompt to that agent's stdin
 cy send <keyword> "" --code=ctrl-c     # send a Ctrl+C
+cy attach <keyword>                    # interactive attach (detach: Ctrl-\)
+cy stop <keyword>                      # graceful shutdown (claude/codex: /exit)
 ```
 
+#### Tips
+
+- A **single** `--code=ctrl-c` does not stop `claude` / `codex` — they treat it
+  as "cancel current turn" rather than "quit". Prefer `cy stop <keyword>` (which
+  sends `/exit` for claude/codex and `/quit` for gemini), or send Ctrl+C twice
+  in quick succession. The `cy send … --code=ctrl-c` output prints a one-line
+  hint pointing at this when it detects one of those CLIs.
+
 `cy` (and `ay` / `agent-yes`) writes to a shared registry at
 `~/.agent-yes/pids.jsonl` and a per-pid FIFO at `~/.agent-yes/fifo/<pid>.stdin`,
 so subcommands work whether the target agent is the TS or Rust runtime.

package/dist/{SUPPORTED_CLIS-yRq_h-h6.js → SUPPORTED_CLIS-BrUEk9Ws.js}

@@ -1,6 +1,6 @@
-import { t as CLIS_CONFIG } from "./ts-CTqyDzUi.js";
+import { t as CLIS_CONFIG } from "./ts-T6n6lrQG.js";
 import "./logger-B9h0djqx.js";
-import "./versionChecker-puPia13W.js";
+import "./versionChecker-Go0xdcmN.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-yRq_h-h6.js.map
+//# sourceMappingURL=SUPPORTED_CLIS-BrUEk9Ws.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-puPia13W.js";
+import { i as versionString, n as displayVersion, r as getInstalledPackage, t as checkAndAutoUpdate } from "./versionChecker-Go0xdcmN.js";
 import { argv } from "process";
 import { execFileSync, spawn } from "child_process";
 import ms from "ms";
@@ -482,7 +482,7 @@ function buildRustArgs(argv, cliFromScript, supportedClis) {
 {
 	const rawArg = process.argv[2];
 	const isHelpFlag = rawArg === "-h" || rawArg === "--help";
-	const { isSubcommand, runSubcommand, cmdHelp } = await import("./subcommands-DIxUhK0D.js");
+	const { isSubcommand, runSubcommand, cmdHelp } = await import("./subcommands-D5WYWmh-.js");
 	if (isHelpFlag && process.argv.length === 3) {
 		cmdHelp();
 		process.exit(0);
@@ -515,7 +515,7 @@ if (config.useRust) {
 		}
 	}
 	if (rustBinary) {
-		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-yRq_h-h6.js");
+		const { SUPPORTED_CLIS } = await import("./SUPPORTED_CLIS-BrUEk9Ws.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-CTqyDzUi.js";
+import { a as removeControlCharacters, i as AgentContext, n as agentYes, r as config, t as CLIS_CONFIG } from "./ts-T6n6lrQG.js";
 import "./logger-B9h0djqx.js";
-import "./versionChecker-puPia13W.js";
+import "./versionChecker-Go0xdcmN.js";
 import "./pidStore-C1JXxoPi.js";
 import "./globalPidIndex-Cr-g75QF.js";
 

package/dist/{serve-CHhrOT6F.js → serve-BYPX6VXm.js}

@@ -1,7 +1,7 @@
 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, l as resolveOne, n as controlCodeFromName, s as readNotes } from "./subcommands-Czbgwuy-.js";
+import { c as readNotes, f as snapshotStatus, l as renderRawLog, m as writeToIpc, o as listRecords, r as controlCodeFromName, u as resolveOne } from "./subcommands-LRmJ4_iJ.js";
 import yargs from "yargs";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { homedir } from "os";
@@ -312,4 +312,4 @@ Options:
 
 //#endregion
 export { cmdServe };
-//# sourceMappingURL=serve-CHhrOT6F.js.map
+//# sourceMappingURL=serve-BYPX6VXm.js.map

package/dist/subcommands-D5WYWmh-.js

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

package/dist/{subcommands-Czbgwuy-.js → subcommands-LRmJ4_iJ.js}

@@ -126,6 +126,8 @@ const SUBCOMMANDS = new Set([
 	"tail",
 	"head",
 	"send",
+	"attach",
+	"stop",
 	"restart",
 	"note",
 	"serve",
@@ -155,10 +157,12 @@ async function runSubcommand(argv) {
 			case "tail": return await cmdRead(rest, { mode: "tail" });
 			case "head": return await cmdRead(rest, { mode: "head" });
 			case "send": return await cmdSend(rest);
+			case "attach": return await cmdAttach(rest);
+			case "stop": return await cmdStop(rest);
 			case "restart": return await cmdRestart(rest);
 			case "note": return await cmdNote(rest);
 			case "serve": {
-				const { cmdServe } = await import("./serve-CHhrOT6F.js");
+				const { cmdServe } = await import("./serve-BYPX6VXm.js");
 				return cmdServe(rest);
 			}
 			case "remote": {
@@ -175,7 +179,7 @@ async function runSubcommand(argv) {
 	}
 }
 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");
+	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 attach <keyword>                 interactive attach (detach: Ctrl-\\)\n  ay stop <keyword>                   graceful shutdown (/exit for claude/codex)\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 at https://github.com/snomiao/agent-yes/tree/main/lab):\n  local-role-play/   designer + builder on one machine\n  http-remote/       ay serve remote access demo\n  p2p-pairing/       libp2p P2P  (needs: cargo build --features swarm)\n");
 	return 0;
 }
 function matchKeyword(record, keyword) {
@@ -953,8 +957,22 @@ async function cmdSend(rest) {
 	process.stdout.write(`sent to pid ${record.pid} (${record.cli}): ${truncate(payload, 80)}\n`);
 	const replyHint = sourcePid ? `  ay send ${sourcePid} "..."              # reply to sender\n` : "";
 	process.stderr.write(`\n` + replyHint + `  ay tail ${record.pid}                  # watch output\n  ay ls                                  # list all agents\n`);
+	if (codeName === "ctrl-c" || codeName === "ctrlc") {
+		const tip = stopTipForCli(record.cli, record.pid);
+		if (tip) process.stderr.write(tip);
+	}
 	return 0;
 }
+function stopTipForCli(cli, pid) {
+	const cmd = GRACEFUL_EXIT_COMMANDS[cli];
+	if (cmd) return `  tip: ${cli} ignores a single Ctrl+C — try 'ay stop ${pid}' (sends '${cmd}') or double Ctrl+C.\n`;
+	return null;
+}
+const GRACEFUL_EXIT_COMMANDS = {
+	claude: "/exit",
+	codex: "/exit",
+	gemini: "/quit"
+};
 function controlCodeFromName(name) {
 	switch (name) {
 		case "enter":
@@ -968,6 +986,9 @@ function controlCodeFromName(name) {
 		case "ctrly": return "";
 		case "ctrl-d":
 		case "ctrld": return "";
+		case "ctrl-\\":
+		case "ctrl\\":
+		case "ctrl-backslash": return "";
 		case "tab": return "	";
 		case "none":
 		case "": return "";
@@ -1007,6 +1028,239 @@ async function writeToIpc(ipcPath, payload) {
 		}
 	}
 }
+async function cmdStop(rest) {
+	const argv = await yargs(rest).usage("Usage: ay stop <keyword> [--method=graceful|double-ctrl-c|auto]").option("method", {
+		type: "string",
+		default: "auto",
+		description: "Shutdown strategy: auto (per-CLI), graceful (/exit-style), double-ctrl-c (force)"
+	}).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;
+	if (!keyword) throw new Error("usage: ay stop <keyword> [--method=auto|graceful|double-ctrl-c]");
+	const record = await resolveOne(keyword, opts);
+	if (!record.fifo_file) throw new Error(`pid ${record.pid}: no fifo_file — cannot send shutdown command`);
+	const method = String(argv.method).toLowerCase();
+	const graceful = GRACEFUL_EXIT_COMMANDS[record.cli];
+	let payload;
+	let strategy;
+	if (method === "double-ctrl-c") {
+		payload = "double-ctrl-c";
+		strategy = `double Ctrl+C (forced)`;
+	} else if (method === "graceful" || method === "auto" && graceful) {
+		if (!graceful) throw new Error(`--method=graceful: no known graceful-exit command for cli "${record.cli}"`);
+		payload = graceful;
+		strategy = `'${graceful}' + Enter`;
+	} else if (method === "auto") {
+		payload = "double-ctrl-c";
+		strategy = `double Ctrl+C (no known /exit for cli "${record.cli}")`;
+	} else throw new Error(`unknown --method=${method}`);
+	const fifoPath = record.fifo_file;
+	if (payload === "double-ctrl-c") {
+		await writeToIpc(fifoPath, "");
+		await new Promise((r) => setTimeout(r, 200));
+		await writeToIpc(fifoPath, "");
+	} else {
+		await writeToIpc(fifoPath, payload);
+		await new Promise((r) => setTimeout(r, 200));
+		await writeToIpc(fifoPath, "\r");
+	}
+	process.stdout.write(`stopping pid ${record.pid} (${record.cli}) via ${strategy}\n`);
+	process.stderr.write(`\n  ay status ${record.pid}                # confirm it exited\n  ay ls --all                            # see exit codes\n`);
+	return 0;
+}
+async function cmdAttach(rest) {
+	const argv = await yargs(rest).usage("Usage: ay attach <keyword> [--escape ctrl-\\]").option("escape", {
+		type: "string",
+		default: "ctrl-\\",
+		description: "Detach key name (see --code list; default: ctrl-\\)"
+	}).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;
+	if (!keyword) throw new Error("usage: ay attach <keyword> [--escape ctrl-\\]");
+	const escapeName = String(argv.escape).toLowerCase();
+	const detachSeq = controlCodeFromName(escapeName);
+	if (!detachSeq) throw new Error(`--escape must resolve to a non-empty byte sequence (got "${argv.escape}")`);
+	const detachByte = detachSeq.charCodeAt(0);
+	const record = await resolveOne(keyword, opts);
+	if (!record.fifo_file) throw new Error(`pid ${record.pid}: no fifo_file recorded — agent has no input channel`);
+	if (!record.log_file) throw new Error(`pid ${record.pid}: no log_file recorded — cannot stream output`);
+	if (!isPidAlive(record.pid)) throw new Error(`pid ${record.pid}: process is not alive`);
+	const fifoPath = record.fifo_file;
+	const logPath = record.log_file;
+	const REPLAY_CAP_BYTES = 1024 * 1024;
+	let initialOffset = 0;
+	let replay = "";
+	try {
+		const st = await stat(logPath);
+		initialOffset = Number(st.size);
+		if (initialOffset > 0) {
+			const readStart = Math.max(0, initialOffset - REPLAY_CAP_BYTES);
+			const fh = await open(logPath, "r");
+			try {
+				const buf = Buffer.alloc(initialOffset - readStart);
+				await fh.read(buf, 0, buf.length, readStart);
+				replay = await renderRawLog(buf, {
+					mode: "tail",
+					n: process.stdout.rows ?? 50
+				});
+			} finally {
+				await fh.close();
+			}
+		}
+	} catch {}
+	process.stderr.write(`[attaching to pid ${record.pid}: ${record.cli} in ${shortenPath(record.cwd)}]\n[detach: ${escapeName}]\n`);
+	if (replay) {
+		process.stdout.write(replay);
+		if (!replay.endsWith("\n")) process.stdout.write("\n");
+	}
+	const ayHome = process.env.AGENT_YES_HOME ?? path.join(homedir(), ".agent-yes");
+	const winsizeDir = path.join(ayHome, "winsize");
+	await mkdir(winsizeDir, { recursive: true });
+	const winsizePath = path.join(winsizeDir, String(record.pid));
+	const sendResize = async () => {
+		const cols = process.stdout.columns ?? 80;
+		const rows = process.stdout.rows ?? 24;
+		try {
+			await writeFile(winsizePath, `${cols} ${rows} ${Date.now()}\n`);
+			try {
+				process.kill(record.pid, "SIGWINCH");
+			} catch {}
+		} catch {}
+	};
+	await sendResize();
+	await new Promise((r) => setTimeout(r, 50));
+	const stdinIsTty = !!process.stdin.isTTY;
+	if (stdinIsTty) try {
+		process.stdin.setRawMode(true);
+	} catch {}
+	process.stdin.resume();
+	const onResize = () => {
+		sendResize();
+	};
+	process.stdout.on("resize", onResize);
+	const { openSync, writeSync, closeSync, watch } = await import("fs");
+	let fifoFd = null;
+	try {
+		fifoFd = openSync(fifoPath, "w");
+	} catch (err) {
+		throw new Error(`failed to open FIFO ${fifoPath}: ${err.message}`);
+	}
+	let offset = initialOffset;
+	let detached = false;
+	let pollTimer;
+	let aliveCheck;
+	const flushNew = async () => {
+		if (detached) return;
+		try {
+			const st = await stat(logPath);
+			if (st.size < offset) offset = 0;
+			if (st.size > offset) {
+				const fh = await open(logPath, "r");
+				try {
+					const buf = Buffer.alloc(st.size - offset);
+					await fh.read(buf, 0, buf.length, offset);
+					process.stdout.write(buf);
+					offset = st.size;
+				} finally {
+					await fh.close();
+				}
+			}
+		} catch {}
+	};
+	const watcher = watch(logPath, () => {
+		flushNew();
+	});
+	await flushNew();
+	pollTimer = setInterval(() => {
+		flushNew();
+	}, 100);
+	const triggerDetach = () => {
+		if (detached) return;
+		detached = true;
+		if (pollTimer) clearInterval(pollTimer);
+		if (aliveCheck) clearInterval(aliveCheck);
+		watcher.close();
+		process.stdout.removeListener("resize", onResize);
+		process.stdin.removeListener("data", onStdinData);
+		if (stdinIsTty) try {
+			process.stdin.setRawMode(false);
+		} catch {}
+		process.stdin.pause();
+		if (fifoFd !== null) {
+			try {
+				closeSync(fifoFd);
+			} catch {}
+			fifoFd = null;
+		}
+		process.stderr.write(`\n[detached from pid ${record.pid} — agent still running]\n`);
+	};
+	const onStdinData = (chunk) => {
+		if (detached) return;
+		const idx = chunk.indexOf(detachByte);
+		if (idx === -1) {
+			try {
+				if (fifoFd !== null) writeSync(fifoFd, chunk);
+			} catch (err) {
+				process.stderr.write(`\n[fifo write failed: ${err.message}]\n`);
+				triggerDetach();
+			}
+			return;
+		}
+		if (idx > 0 && fifoFd !== null) try {
+			writeSync(fifoFd, chunk.subarray(0, idx));
+		} catch {}
+		triggerDetach();
+	};
+	process.stdin.on("data", onStdinData);
+	aliveCheck = setInterval(() => {
+		if (!isPidAlive(record.pid)) {
+			process.stderr.write(`\n[pid ${record.pid} exited]\n`);
+			triggerDetach();
+		}
+	}, 1e3);
+	await new Promise((resolve) => {
+		const tick = () => {
+			if (detached) resolve();
+			else setTimeout(tick, 50);
+		};
+		tick();
+	});
+	return 0;
+}
 async function cmdRestart(rest) {
 	const argv = await yargs(rest).usage("Usage: ay restart <keyword>").option("latest", {
 		type: "boolean",
@@ -1192,5 +1446,5 @@ async function cmdStatus(rest) {
 }
 
 //#endregion
-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-Czbgwuy-.js.map
+export { isSubcommand as a, readNotes as c, runSubcommand as d, snapshotStatus as f, isPidAlive as i, renderRawLog as l, writeToIpc as m, cmdHelp as n, listRecords as o, stopTipForCli as p, controlCodeFromName as r, matchKeyword as s, GRACEFUL_EXIT_COMMANDS as t, resolveOne as u };
+//# sourceMappingURL=subcommands-LRmJ4_iJ.js.map

package/dist/{ts-CTqyDzUi.js → ts-T6n6lrQG.js}

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

package/dist/{versionChecker-puPia13W.js → versionChecker-Go0xdcmN.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-yes",
-  "version": "1.89.0",
+  "version": "1.90.1",
   "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

@@ -36,6 +36,8 @@ describe("subcommands.controlCodeFromName", () => {
     expect(controlCodeFromName("ctrl-c")).toBe("\x03");
     expect(controlCodeFromName("ctrl-y")).toBe("\x19");
     expect(controlCodeFromName("ctrl-d")).toBe("\x04");
+    expect(controlCodeFromName("ctrl-\\")).toBe("\x1c");
+    expect(controlCodeFromName("ctrl-backslash")).toBe("\x1c");
     expect(controlCodeFromName("tab")).toBe("\t");
     expect(controlCodeFromName("none")).toBe("");
     expect(controlCodeFromName("")).toBe("");
@@ -53,6 +55,43 @@ describe("subcommands.controlCodeFromName", () => {
   });
 });
 
+describe("subcommands.isSubcommand", () => {
+  it("recognises attach and stop alongside the existing subcommands", async () => {
+    const { isSubcommand } = await loadModule();
+    expect(isSubcommand("attach")).toBe(true);
+    expect(isSubcommand("stop")).toBe(true);
+    expect(isSubcommand("tail")).toBe(true);
+    expect(isSubcommand("send")).toBe(true);
+    expect(isSubcommand("not-a-command")).toBe(false);
+    expect(isSubcommand(undefined)).toBe(false);
+  });
+});
+
+describe("subcommands.stopTipForCli", () => {
+  it("returns a hint for CLIs that ignore single Ctrl+C", async () => {
+    const { stopTipForCli } = await loadModule();
+    expect(stopTipForCli("claude", 1234)).toMatch(/ay stop 1234/);
+    expect(stopTipForCli("claude", 1234)).toMatch(/\/exit/);
+    expect(stopTipForCli("codex", 99)).toMatch(/ay stop 99/);
+    expect(stopTipForCli("gemini", 7)).toMatch(/\/quit/);
+  });
+
+  it("returns null for CLIs without a known graceful command", async () => {
+    const { stopTipForCli } = await loadModule();
+    expect(stopTipForCli("qwen", 1)).toBeNull();
+    expect(stopTipForCli("copilot", 1)).toBeNull();
+  });
+});
+
+describe("subcommands.GRACEFUL_EXIT_COMMANDS", () => {
+  it("maps the three known CLIs to their /exit-style commands", async () => {
+    const { GRACEFUL_EXIT_COMMANDS } = await loadModule();
+    expect(GRACEFUL_EXIT_COMMANDS["claude"]).toBe("/exit");
+    expect(GRACEFUL_EXIT_COMMANDS["codex"]).toBe("/exit");
+    expect(GRACEFUL_EXIT_COMMANDS["gemini"]).toBe("/quit");
+  });
+});
+
 describe("subcommands.matchKeyword", () => {
   const baseRecord = {
     pid: 1234,

package/ts/subcommands.ts

@@ -136,6 +136,8 @@ const SUBCOMMANDS = new Set([
   "tail",
   "head",
   "send",
+  "attach",
+  "stop",
   "restart",
   "note",
   "serve",
@@ -176,6 +178,10 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
         return await cmdRead(rest, { mode: "head" });
       case "send":
         return await cmdSend(rest);
+      case "attach":
+        return await cmdAttach(rest);
+      case "stop":
+        return await cmdStop(rest);
       case "restart":
         return await cmdRestart(rest);
       case "note":
@@ -214,6 +220,8 @@ export function cmdHelp(): number {
       `  ay cat <keyword>                    full log\n` +
       `  ay head <keyword>                   first N lines\n` +
       `  ay send <keyword> <msg>             send a message\n` +
+      `  ay attach <keyword>                 interactive attach (detach: Ctrl-\\)\n` +
+      `  ay stop <keyword>                   graceful shutdown (/exit for claude/codex)\n` +
       `  ay status <keyword>                 agent status snapshot\n` +
       `\n` +
       `Remote:\n` +
@@ -228,7 +236,7 @@ export function cmdHelp(): number {
       `  ay claude -- "fix the bug in auth.ts"\n` +
       `  ay claude --help                    full agent-runner options\n` +
       `\n` +
-      `Labs (examples in ./lab/):\n` +
+      `Labs (examples at https://github.com/snomiao/agent-yes/tree/main/lab):\n` +
       `  local-role-play/   designer + builder on one machine\n` +
       `  http-remote/       ay serve remote access demo\n` +
       `  p2p-pairing/       libp2p P2P  (needs: cargo build --features swarm)\n`,
@@ -1328,9 +1336,37 @@ async function cmdSend(rest: string[]): Promise<number> {
       `  ay tail ${record.pid}                  # watch output\n` +
       `  ay ls                                  # list all agents\n`,
   );
+  if (codeName === "ctrl-c" || codeName === "ctrlc") {
+    const tip = stopTipForCli(record.cli, record.pid);
+    if (tip) process.stderr.write(tip);
+  }
   return 0;
 }
 
+/// CLIs that ignore a single Ctrl+C and need a more specific shutdown signal.
+/// Users hit this every time they try `ay send <pid> "" --code=ctrl-c` and
+/// see no effect — print a one-liner pointing them at `ay stop`.
+export function stopTipForCli(cli: string, pid: number): string | null {
+  const cmd = GRACEFUL_EXIT_COMMANDS[cli];
+  if (cmd) {
+    return `  tip: ${cli} ignores a single Ctrl+C — try 'ay stop ${pid}' (sends '${cmd}') or double Ctrl+C.\n`;
+  }
+  return null;
+}
+
+/// Per-CLI graceful shutdown commands. Empty fallback = use double Ctrl+C.
+/// Verified against current upstream CLIs:
+///   claude   — `/exit`
+///   codex    — `/exit`
+///   gemini   — `/quit`
+/// Other CLIs aren't in the table because their reliable graceful-exit
+/// command isn't well-known here; `ay stop` falls back to double Ctrl+C.
+export const GRACEFUL_EXIT_COMMANDS: Record<string, string> = {
+  claude: "/exit",
+  codex: "/exit",
+  gemini: "/quit",
+};
+
 export function controlCodeFromName(name: string): string {
   switch (name) {
     case "enter":
@@ -1349,6 +1385,13 @@ export function controlCodeFromName(name: string): string {
     case "ctrl-d":
     case "ctrld":
       return "\x04";
+    case "ctrl-\\":
+    case "ctrl\\":
+    case "ctrl-backslash":
+      // FS (file separator); convenient detach key for `ay attach`
+      // because few CLIs send it. Same as SIGQUIT's terminal binding,
+      // but here it's intercepted before reaching any signal handler.
+      return "\x1c";
     case "tab":
       return "\t";
     case "none":
@@ -1393,6 +1436,325 @@ export async function writeToIpc(ipcPath: string, payload: string): Promise<void
   }
 }
 
+// ---------------------------------------------------------------------------
+// ay stop
+// ---------------------------------------------------------------------------
+
+async function cmdStop(rest: string[]): Promise<number> {
+  const y = yargs(rest)
+    .usage("Usage: ay stop <keyword> [--method=graceful|double-ctrl-c|auto]")
+    .option("method", {
+      type: "string",
+      default: "auto",
+      description:
+        "Shutdown strategy: auto (per-CLI), graceful (/exit-style), double-ctrl-c (force)",
+    })
+    .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;
+  if (!keyword) throw new Error("usage: ay stop <keyword> [--method=auto|graceful|double-ctrl-c]");
+
+  const record = await resolveOne(keyword, opts);
+  if (!record.fifo_file) {
+    throw new Error(`pid ${record.pid}: no fifo_file — cannot send shutdown command`);
+  }
+
+  const method = String(argv.method).toLowerCase();
+  const graceful = GRACEFUL_EXIT_COMMANDS[record.cli];
+
+  let payload: string;
+  let strategy: string;
+  if (method === "double-ctrl-c") {
+    payload = "double-ctrl-c";
+    strategy = `double Ctrl+C (forced)`;
+  } else if (method === "graceful" || (method === "auto" && graceful)) {
+    if (!graceful) {
+      throw new Error(`--method=graceful: no known graceful-exit command for cli "${record.cli}"`);
+    }
+    payload = graceful;
+    strategy = `'${graceful}' + Enter`;
+  } else if (method === "auto") {
+    payload = "double-ctrl-c";
+    strategy = `double Ctrl+C (no known /exit for cli "${record.cli}")`;
+  } else {
+    throw new Error(`unknown --method=${method}`);
+  }
+
+  const fifoPath = record.fifo_file;
+  if (payload === "double-ctrl-c") {
+    await writeToIpc(fifoPath, "\x03");
+    await new Promise((r) => setTimeout(r, 200));
+    await writeToIpc(fifoPath, "\x03");
+  } else {
+    await writeToIpc(fifoPath, payload);
+    await new Promise((r) => setTimeout(r, 200));
+    await writeToIpc(fifoPath, "\r");
+  }
+
+  process.stdout.write(`stopping pid ${record.pid} (${record.cli}) via ${strategy}\n`);
+  process.stderr.write(
+    `\n` +
+      `  ay status ${record.pid}                # confirm it exited\n` +
+      `  ay ls --all                            # see exit codes\n`,
+  );
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// ay attach
+// ---------------------------------------------------------------------------
+
+async function cmdAttach(rest: string[]): Promise<number> {
+  const y = yargs(rest)
+    .usage("Usage: ay attach <keyword> [--escape ctrl-\\]")
+    .option("escape", {
+      type: "string",
+      default: "ctrl-\\",
+      description: "Detach key name (see --code list; default: ctrl-\\)",
+    })
+    .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;
+  if (!keyword) throw new Error("usage: ay attach <keyword> [--escape ctrl-\\]");
+
+  const escapeName = String(argv.escape).toLowerCase();
+  const detachSeq = controlCodeFromName(escapeName);
+  if (!detachSeq) {
+    throw new Error(`--escape must resolve to a non-empty byte sequence (got "${argv.escape}")`);
+  }
+  const detachByte = detachSeq.charCodeAt(0);
+
+  const record = await resolveOne(keyword, opts);
+  if (!record.fifo_file) {
+    throw new Error(`pid ${record.pid}: no fifo_file recorded — agent has no input channel`);
+  }
+  if (!record.log_file) {
+    throw new Error(`pid ${record.pid}: no log_file recorded — cannot stream output`);
+  }
+  if (!isPidAlive(record.pid)) {
+    throw new Error(`pid ${record.pid}: process is not alive`);
+  }
+
+  const fifoPath = record.fifo_file;
+  const logPath = record.log_file;
+
+  // 1. Replay the current screen via @xterm/headless so the user sees a
+  //    coherent snapshot instead of half-frame ANSI garbage. Cap input bytes
+  //    so multi-MB logs don't stall the attach.
+  const REPLAY_CAP_BYTES = 1024 * 1024;
+  let initialOffset = 0;
+  let replay = "";
+  try {
+    const st = await stat(logPath);
+    initialOffset = Number(st.size);
+    if (initialOffset > 0) {
+      const readStart = Math.max(0, initialOffset - REPLAY_CAP_BYTES);
+      const fh = await open(logPath, "r");
+      try {
+        const buf = Buffer.alloc(initialOffset - readStart);
+        await fh.read(buf, 0, buf.length, readStart);
+        const rows = process.stdout.rows ?? 50;
+        replay = await renderRawLog(buf, { mode: "tail", n: rows });
+      } finally {
+        await fh.close();
+      }
+    }
+  } catch {
+    /* log unreadable — show nothing */
+  }
+
+  process.stderr.write(
+    `[attaching to pid ${record.pid}: ${record.cli} in ${shortenPath(record.cwd)}]\n` +
+      `[detach: ${escapeName}]\n`,
+  );
+  if (replay) {
+    process.stdout.write(replay);
+    if (!replay.endsWith("\n")) process.stdout.write("\n");
+  }
+
+  // 2. Push local winsize → ~/.agent-yes/winsize/<pid>, signal SIGWINCH so
+  //    the agent resizes its inner PTY before we start forwarding bytes.
+  const ayHome = process.env.AGENT_YES_HOME ?? path.join(homedir(), ".agent-yes");
+  const winsizeDir = path.join(ayHome, "winsize");
+  await mkdir(winsizeDir, { recursive: true });
+  const winsizePath = path.join(winsizeDir, String(record.pid));
+
+  const sendResize = async () => {
+    const cols = process.stdout.columns ?? 80;
+    const rows = process.stdout.rows ?? 24;
+    try {
+      await writeFile(winsizePath, `${cols} ${rows} ${Date.now()}\n`);
+      try {
+        process.kill(record.pid, "SIGWINCH");
+      } catch {
+        /* agent died — handled by alive check */
+      }
+    } catch {
+      /* ignore */
+    }
+  };
+  await sendResize();
+  await new Promise((r) => setTimeout(r, 50)); // let agent redraw
+
+  // 3. Raw TTY so per-keystroke bytes flow through unchanged.
+  const stdinIsTty = !!process.stdin.isTTY;
+  if (stdinIsTty) {
+    try {
+      process.stdin.setRawMode(true);
+    } catch {
+      /* ignore */
+    }
+  }
+  process.stdin.resume();
+
+  const onResize = () => {
+    void sendResize();
+  };
+  process.stdout.on("resize", onResize);
+
+  // 4. Keep FIFO open across keystrokes so we don't pay open(2) per byte.
+  //    Agent's RDWR keepalive means O_WRONLY does not block here.
+  const { openSync, writeSync, closeSync, watch } = await import("fs");
+  let fifoFd: number | null = null;
+  try {
+    fifoFd = openSync(fifoPath, "w");
+  } catch (err) {
+    throw new Error(`failed to open FIFO ${fifoPath}: ${(err as Error).message}`);
+  }
+
+  // 5. Stream new log bytes → stdout. fs.watch may coalesce on macOS, so
+  //    poll every 100ms as a safety net.
+  let offset = initialOffset;
+  let detached = false;
+  let pollTimer: NodeJS.Timeout | undefined;
+  let aliveCheck: NodeJS.Timeout | undefined;
+
+  const flushNew = async () => {
+    if (detached) return;
+    try {
+      const st = await stat(logPath);
+      if (st.size < offset) offset = 0; // truncated
+      if (st.size > offset) {
+        const fh = await open(logPath, "r");
+        try {
+          const buf = Buffer.alloc(st.size - offset);
+          await fh.read(buf, 0, buf.length, offset);
+          process.stdout.write(buf);
+          offset = st.size;
+        } finally {
+          await fh.close();
+        }
+      }
+    } catch {
+      /* transient — retry */
+    }
+  };
+
+  const watcher = watch(logPath, () => {
+    void flushNew();
+  });
+  // Race fix: bytes can land between stat() above and watch() install.
+  await flushNew();
+  pollTimer = setInterval(() => {
+    void flushNew();
+  }, 100);
+
+  // 6. Stdin → FIFO, watching for detach byte.
+  const triggerDetach = () => {
+    if (detached) return;
+    detached = true;
+    if (pollTimer) clearInterval(pollTimer);
+    if (aliveCheck) clearInterval(aliveCheck);
+    watcher.close();
+    process.stdout.removeListener("resize", onResize);
+    process.stdin.removeListener("data", onStdinData);
+    if (stdinIsTty) {
+      try {
+        process.stdin.setRawMode(false);
+      } catch {
+        /* ignore */
+      }
+    }
+    process.stdin.pause();
+    if (fifoFd !== null) {
+      try {
+        closeSync(fifoFd);
+      } catch {
+        /* ignore */
+      }
+      fifoFd = null;
+    }
+    process.stderr.write(`\n[detached from pid ${record.pid} — agent still running]\n`);
+  };
+
+  const onStdinData = (chunk: Buffer) => {
+    if (detached) return;
+    const idx = chunk.indexOf(detachByte);
+    if (idx === -1) {
+      try {
+        if (fifoFd !== null) writeSync(fifoFd, chunk);
+      } catch (err) {
+        process.stderr.write(`\n[fifo write failed: ${(err as Error).message}]\n`);
+        triggerDetach();
+      }
+      return;
+    }
+    if (idx > 0 && fifoFd !== null) {
+      try {
+        writeSync(fifoFd, chunk.subarray(0, idx));
+      } catch {
+        /* ignore */
+      }
+    }
+    triggerDetach();
+  };
+  process.stdin.on("data", onStdinData);
+
+  // 7. Detach automatically if the agent exits.
+  aliveCheck = setInterval(() => {
+    if (!isPidAlive(record.pid)) {
+      process.stderr.write(`\n[pid ${record.pid} exited]\n`);
+      triggerDetach();
+    }
+  }, 1000);
+
+  await new Promise<void>((resolve) => {
+    const tick = () => {
+      if (detached) resolve();
+      else setTimeout(tick, 50);
+    };
+    tick();
+  });
+
+  return 0;
+}
+
 // ---------------------------------------------------------------------------
 // ay restart
 // ---------------------------------------------------------------------------

package/dist/subcommands-DIxUhK0D.js

@@ -1,6 +0,0 @@
-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-Czbgwuy-.js";
-
-export { cmdHelp, isSubcommand, runSubcommand };