agent-yes 1.122.3 → 1.124.0

package/dist/{subcommands-CQowpr1t.js → subcommands-ClVHy-xI.js}

@@ -1,11 +1,300 @@
-import { i as readGlobalPids } from "./globalPidIndex-gZuTvTBs.js";
-import { a as resolveRemoteSpec, i as readRemotes } from "./remotes-D2fqaRU8.js";
+import { t as agentYesHome } from "./agentYesHome-BvaUOzCV.js";
+import { a as updateGlobalPidStatus, i as readGlobalPids } from "./globalPidIndex-C7r2m6s7.js";
+import { t as loadSharedCliDefaults } from "./configShared-C5QaNPnz.js";
+import { a as resolveRemoteSpec, i as readRemotes } from "./remotes-D8GvSbhf.js";
 import ms from "ms";
 import yargs from "yargs";
 import { appendFile, mkdir, open, readFile, stat, writeFile } from "fs/promises";
 import { homedir } from "os";
 import path from "path";
 
+//#region ts/agentTree.ts
+/**
+* Link records into a forest via parent_pid === wrapper_pid. Records whose
+* parent isn't present in the set (top-level agents, or links into agents
+* filtered out by a keyword/scope) become roots. Root and sibling order follows
+* the input order, so a caller that pre-sorts (e.g. newest-first) is preserved.
+*/
+function buildAgentForest(records) {
+	const nodes = records.map((record) => ({
+		record,
+		children: []
+	}));
+	const byWrapper = /* @__PURE__ */ new Map();
+	for (const n of nodes) {
+		const w = n.record.wrapper_pid;
+		if (typeof w === "number" && w > 0) byWrapper.set(w, n);
+	}
+	const roots = [];
+	for (const n of nodes) {
+		const p = n.record.parent_pid;
+		const parent = typeof p === "number" && p > 0 ? byWrapper.get(p) : void 0;
+		if (parent && parent !== n) parent.children.push(n);
+		else roots.push(n);
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const mark = (n) => {
+		if (seen.has(n)) return;
+		seen.add(n);
+		n.children.forEach(mark);
+	};
+	roots.forEach(mark);
+	for (const n of nodes) if (!seen.has(n)) roots.push(n);
+	return roots;
+}
+/**
+* Depth-first flatten a forest into rows carrying a box-drawing branch prefix.
+* A `visited` guard makes a pathological parent_pid cycle terminate instead of
+* recursing forever.
+*/
+function flattenForest(roots) {
+	const rows = [];
+	const visited = /* @__PURE__ */ new Set();
+	const walk = (node, ancestorsLast) => {
+		if (visited.has(node)) return;
+		visited.add(node);
+		const depth = ancestorsLast.length;
+		let prefix = "";
+		for (let i = 0; i < depth - 1; i++) prefix += ancestorsLast[i] ? "   " : "│  ";
+		if (depth > 0) prefix += ancestorsLast[depth - 1] ? "└─ " : "├─ ";
+		rows.push({
+			record: node.record,
+			prefix,
+			depth
+		});
+		node.children.forEach((c, i) => walk(c, [...ancestorsLast, i === node.children.length - 1]));
+	};
+	for (const r of roots) walk(r, []);
+	return rows;
+}
+
+//#endregion
+//#region ts/todoParse.ts
+/**
+* Parse an agent's todo/task list out of its RENDERED TUI screen.
+*
+* Source of truth for EVERY CLI (claude, codex, gemini, …) is the screen the
+* agent draws — never a CLI-specific session file. The durable copy is the
+* per-pid raw log (`<cwd>/.agent-yes/<pid>.raw.log`); rendering it through a
+* headless xterm (see renderRawLog) collapses the reflow/redraw frames into the
+* final coherent text, which is what we scan here.
+*
+* The todo list in these TUIs renders as a tree block anchored by the `⎿`
+* branch glyph, one marker per line:
+*
+*     ⎿  ☒ Wire up the parser
+*        ☒ Add the badge
+*        ◼ Compute in /api/ls      ← in progress
+*        ◻ Render in the console   ← pending
+*        ◻ Tests
+*
+* Badge = `${done}/${total}` (done is the numerator → "2/5").
+*
+* This parse is deliberately conservative: we only report a count when a block
+* is confidently detected (the `⎿` anchor + ≥2 consecutive marker lines), so an
+* agent that merely prints a check glyph in prose never produces a phantom badge.
+*/
+const DONE = new Set([
+	"✔",
+	"☑",
+	"✓",
+	"☒"
+]);
+const IN_PROGRESS = new Set(["◼"]);
+const PENDING = new Set(["◻", "☐"]);
+const ANCHOR = "⎿";
+function markerOf(line) {
+	let s = line.replace(/^\s+/, "");
+	if (s.startsWith(ANCHOR)) s = s.slice(1).replace(/^\s+/, "");
+	const ch = [...s][0];
+	if (ch === void 0) return null;
+	if (DONE.has(ch)) return "done";
+	if (IN_PROGRESS.has(ch)) return "inprogress";
+	if (PENDING.has(ch)) return "pending";
+	return null;
+}
+/**
+* Find the MOST RECENT confidently-detected todo block in the rendered lines and
+* return its {done, total}. Returns null when none qualifies (caller omits the
+* badge entirely — never shows "0/0").
+*
+* A block is a maximal run of consecutive marker lines. It only counts when it
+* is anchored — the `⎿` glyph appears on the run's first line or the line
+* directly above it — and has ≥2 marker lines. The last qualifying block wins,
+* since the agent's current todo state is the one drawn most recently.
+*/
+function parseTaskCounts(lines) {
+	let best = null;
+	const n = lines.length;
+	let i = 0;
+	while (i < n) {
+		if (markerOf(lines[i]) === null) {
+			i++;
+			continue;
+		}
+		let hasAnchor = i > 0 && lines[i - 1].includes(ANCHOR);
+		const counts = {
+			done: 0,
+			inprogress: 0,
+			pending: 0
+		};
+		let j = i;
+		for (; j < n; j++) {
+			const mk = markerOf(lines[j]);
+			if (mk === null) break;
+			if (lines[j].includes(ANCHOR)) hasAnchor = true;
+			counts[mk]++;
+		}
+		const total = counts.done + counts.inprogress + counts.pending;
+		if (hasAnchor && total >= 2) best = {
+			done: counts.done,
+			total
+		};
+		i = j === i ? i + 1 : j;
+	}
+	return best;
+}
+
+//#endregion
+//#region ts/needsInput.ts
+function reTest(re, s) {
+	return (re.global || re.sticky ? new RegExp(re.source, re.flags.replace(/[gy]/g, "")) : re).test(s);
+}
+function isChromeLine(s) {
+	const t = s.trim();
+	return !t || /^─+$/.test(t) || /^esc to (interrupt|cancel)/i.test(t) || /\? for shortcuts/.test(t) || /\d+%\s*until auto-compact/i.test(t);
+}
+/**
+* Returns a NeedsInput when the screen shows an unresolved selection menu, else
+* null. `cfg.working` short-circuits to null (an actively-working agent isn't
+* blocked). Pure + synchronous so it's trivially unit-testable.
+*/
+function classifyNeedsInput(lines, cfg) {
+	const patterns = cfg.needsInput ?? [];
+	if (patterns.length === 0) return null;
+	const text = lines.join("\n");
+	if ((cfg.working ?? []).some((re) => reTest(re, text))) return null;
+	if (!patterns.some((re) => reTest(re, text))) return null;
+	let last = -1;
+	for (let i = 0; i < lines.length; i++) if (patterns.some((re) => reTest(re, lines[i]))) last = i;
+	const start = Math.max(0, last - 6);
+	const end = Math.min(lines.length, last + 6);
+	return { question: lines.slice(start, end).map((l) => l.trim()).filter((l) => l && !isChromeLine(l)).join(" • ").slice(0, 400) };
+}
+
+//#endregion
+//#region ts/lsWatch.ts
+/**
+* Diff the previous per-pid states against the current snapshot and return the
+* transition events to emit plus the next prev-map. Pure: no I/O, no clock —
+* the caller passes `ts`.
+*
+* Emits an event when:
+*  - an agent is seen for the first time (baseline, `prev_state: null`)
+*  - its `state` or `question` changed since last tick
+*  - it vanished from the live set without us ever seeing it `stopped` (reaped
+*    between ticks) — a synthetic `stopped` event so a "done" transition is
+*    never silently dropped.
+*/
+function diffLsStates(prev, cur, ts) {
+	const events = [];
+	const next = /* @__PURE__ */ new Map();
+	const curPids = /* @__PURE__ */ new Set();
+	for (const a of cur) {
+		curPids.add(a.pid);
+		next.set(a.pid, a);
+		const p = prev.get(a.pid);
+		if (!p) events.push({
+			...toEvent(a, ts),
+			prev_state: null
+		});
+		else if (p.state !== a.state || p.question !== a.question) events.push({
+			...toEvent(a, ts),
+			prev_state: p.state
+		});
+	}
+	for (const [pid, p] of prev) if (!curPids.has(pid) && p.state !== "stopped") events.push({
+		ts,
+		pid,
+		cli: p.cli,
+		cwd: p.cwd,
+		state: "stopped",
+		question: null,
+		prev_state: p.state
+	});
+	return {
+		events,
+		next
+	};
+}
+function toEvent(a, ts) {
+	return {
+		ts,
+		pid: a.pid,
+		cli: a.cli,
+		cwd: a.cwd,
+		state: a.state,
+		question: a.question
+	};
+}
+
+//#endregion
+//#region ts/resultEnvelope.ts
+/**
+* Structured result envelope — P4 of the orchestrator-observability work.
+*
+* A fan-out parent that spawned a sub-agent wants its *outcome* (branch, commit
+* SHAs, changed files, status, blockers, a summary) as machine-readable data,
+* not by grepping `ay tail`. This is the agent-yes analog of an in-harness
+* Agent tool's `<result>` block. The sub-agent deposits one JSON envelope when
+* it finishes; the parent pulls it with `ay result <keyword>`.
+*
+* Why a PERSISTED file, not a query-time screen scrape (the model that
+* `needs_input`/activity use): a completion record is read AFTER the agent is
+* done — exactly when its rendered screen is gone and its log may be reaped. It
+* must outlive the process, so it is written once to
+* `$AGENT_YES_HOME/results/<pid>.json` and read back verbatim. It is keyed by
+* the wrapper pid the agent already knows via the injected `AGENT_YES_PID` env
+* var, so depositing needs no new spawn-time wiring in either runtime.
+*
+* This module is the pure, fs-free core (path math + input normalization) so it
+* is trivially unit-testable, mirroring `lsWatch.ts` / `needsInput.ts`. The fs
+* read/write + CLI live in `subcommands.ts` (`cmdResult`).
+*/
+/** Directory holding the per-pid result files. */
+function resultsDir() {
+	return path.join(agentYesHome(), "results");
+}
+/** Absolute path of one agent's result envelope. */
+function resultPath(pid) {
+	return path.join(resultsDir(), `${pid}.json`);
+}
+/**
+* Coerce raw write-side input into an envelope payload. If it parses as JSON we
+* keep it as-is (object, array, or scalar — the agent owns the shape). If it
+* does NOT parse, we don't reject: a bare string is a perfectly good summary, so
+* we wrap it as `{ summary }`. Empty / whitespace-only input is an error the
+* caller should surface (returns null).
+*/
+function normalizeEnvelope(raw) {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return null;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return { summary: trimmed };
+	}
+}
+/** Wrap a normalized payload with correlation metadata for persistence. */
+function buildStoredResult(pid, result, writtenAt) {
+	return {
+		pid,
+		written_at: writtenAt,
+		result
+	};
+}
+
+//#endregion
 //#region ts/subcommands.ts
 /**
 * `ay ls / read / cat / tail / head / send` subcommand implementations.
@@ -189,6 +478,7 @@ const SUBCOMMANDS = new Set([
 	"list",
 	"ps",
 	"status",
+	"result",
 	"read",
 	"cat",
 	"tail",
@@ -223,6 +513,7 @@ async function runSubcommand(argv) {
 			case "list":
 			case "ps": return await cmdLs(rest);
 			case "status": return await cmdStatus(rest);
+			case "result": return await cmdResult(rest);
 			case "read":
 			case "cat": return await cmdRead(rest, { mode: "cat" });
 			case "tail": return await cmdRead(rest, { mode: "tail" });
@@ -233,23 +524,23 @@ async function runSubcommand(argv) {
 			case "restart": return await cmdRestart(rest);
 			case "note": return await cmdNote(rest);
 			case "serve": {
-				const { cmdServe } = await import("./serve-CzztmZ_N.js");
+				const { cmdServe } = await import("./serve-Bo3bDXQG.js");
 				return cmdServe(rest);
 			}
 			case "setup": {
-				const { cmdSetup } = await import("./setup-CPyRNiIA.js");
+				const { cmdSetup } = await import("./setup-CvOr258q.js");
 				return cmdSetup(rest);
 			}
 			case "schedule": {
-				const { cmdSchedule } = await import("./schedule-e4f7NlA2.js");
+				const { cmdSchedule } = await import("./schedule-D2cn8N7o.js");
 				return cmdSchedule(rest);
 			}
 			case "remote": {
-				const { cmdRemote } = await import("./remotes-CpGcTr7A.js");
+				const { cmdRemote } = await import("./remotes-BRCDVnR7.js");
 				return cmdRemote(rest);
 			}
 			case "reap":
-				await (await import("./reaper-HqcUms2d.js")).sweep();
+				await (await import("./reaper-BLVA780B.js")).sweep();
 				return 0;
 			case "help": return cmdHelp();
 			default: return null;
@@ -261,7 +552,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 attach <keyword>                 interactive attach (detach: Ctrl-\\)\n  ay stop <keyword>                   graceful shutdown (/exit for claude/codex)\n  ay status <keyword>                 agent status snapshot\n  ay reap                             kill process groups leaked by dead agents\n\nRemote:\n  ay setup                            guided setup: pick a workspace, share to agent-yes.com\n  ay schedule <when> <cli> -- <msg>   run an agent on a schedule (HH:MM or cron)\n  ay serve [--port N]                 start HTTP API server (prints token)\n  ay serve status                     show serve daemon/server status\n  ay remote add <alias> http://<token>@<host>:<port>\n  ay remote ls / rm <alias>           manage saved remotes\n  ay 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");
+	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  ay result <keyword> [--wait]        pull an agent's structured result envelope\n  ay result set '<json>'              (inside an agent) deposit your result envelope\n  ay reap                             kill process groups leaked by dead agents\n\nRemote:\n  ay setup                            guided setup: pick a workspace, share to agent-yes.com\n  ay schedule <when> <cli> -- <msg>   run an agent on a schedule (HH:MM or cron)\n  ay serve [--port N]                 start HTTP API server (prints token)\n  ay serve status                     show serve daemon/server status\n  ay remote add <alias> http://<token>@<host>:<port>\n  ay remote ls / rm <alias>           manage saved remotes\n  ay 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) {
@@ -629,6 +920,35 @@ async function runAllRemotesLs(opts) {
 	}
 	return 0;
 }
+/**
+* The live display state of one agent: stopped (exited) / idle (alive+quiet) /
+* active (alive+recent output) / needs_input (alive but parked on an unanswered
+* menu). Shared by the `ay ls` human table AND its `--json` output so both report
+* needs_input identically — an orchestrator parsing `ay ls --json` is the primary
+* consumer.
+*/
+async function deriveLiveState(r) {
+	if (!isPidAlive(r.pid)) return {
+		state: "stopped",
+		question: null
+	};
+	let state = "active";
+	if (r.log_file) {
+		const mtime = await stat(r.log_file).then((s) => s.mtimeMs).catch(() => null);
+		state = mtime !== null && Date.now() - mtime > IDLE_THRESHOLD_MS ? "idle" : "active";
+	}
+	if (r.log_file) {
+		const ni = await extractNeedsInput(r.log_file, r.cli);
+		if (ni) return {
+			state: "needs_input",
+			question: ni.question
+		};
+	}
+	return {
+		state,
+		question: null
+	};
+}
 async function cmdLs(rest) {
 	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",
@@ -642,6 +962,15 @@ async function cmdLs(rest) {
 		type: "boolean",
 		default: false,
 		description: "Output as JSON array"
+	}).option("watch", {
+		alias: "w",
+		type: "boolean",
+		default: false,
+		description: "Stream agent state transitions (needs_input | idle | active | stopped) as NDJSON across all matched agents — one event stream for a whole fan-out, instead of N per-pid `ay status --watch`es. Runs until Ctrl-C."
+	}).option("interval", {
+		type: "number",
+		default: 2,
+		description: "Poll interval in seconds (--watch)"
 	}).option("latest", {
 		type: "boolean",
 		default: false,
@@ -658,7 +987,7 @@ async function cmdLs(rest) {
 		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);
+	}).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 --watch", "stream state transitions for a whole fan-out as NDJSON").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");
@@ -684,9 +1013,45 @@ async function cmdLs(rest) {
 		latest: argv.latest,
 		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
 	};
+	if (argv.watch) {
+		const intervalMs = Math.max(500, (Number.isFinite(argv.interval) ? argv.interval : 2) * 1e3);
+		process.stderr.write(`watching agents every ${intervalMs / 1e3}s… (Ctrl-C to stop)\n`);
+		let prev = /* @__PURE__ */ new Map();
+		const tick = async () => {
+			const recs = await listRecords(keyword, opts);
+			const cur = await Promise.all(recs.map(async (r) => {
+				const { state, question } = await deriveLiveState(r);
+				return {
+					pid: r.pid,
+					cli: r.cli,
+					cwd: r.cwd,
+					state,
+					question
+				};
+			}));
+			const { events, next } = diffLsStates(prev, cur, Date.now());
+			for (const e of events) process.stdout.write(JSON.stringify(e) + "\n");
+			prev = next;
+		};
+		await tick();
+		await new Promise((resolve) => {
+			const timer = setInterval(() => {
+				tick();
+			}, intervalMs);
+			process.on("SIGINT", () => {
+				clearInterval(timer);
+				resolve();
+			});
+		});
+		return 0;
+	}
 	const records = await listRecords(keyword, opts);
 	if (opts.json) {
-		process.stdout.write(JSON.stringify(records, null, 2) + "\n");
+		const enriched = await Promise.all(records.map(async (r) => ({
+			...r,
+			...await deriveLiveState(r)
+		})));
+		process.stdout.write(JSON.stringify(enriched, null, 2) + "\n");
 		return 0;
 	}
 	if (records.length === 0) {
@@ -704,22 +1069,22 @@ async function cmdLs(rest) {
 	};
 	const fixedWidth = widths.pid + widths.cli + widths.status + widths.age + widths.cwd + 10;
 	const promptBudget = Math.max(20, termWidth - fixedWidth - 1);
+	const forestRows = flattenForest(buildAgentForest(records));
 	const notes = await readNotes();
-	const rows = await Promise.all(records.map(async (r) => {
-		let displayStatus;
-		if (!isPidAlive(r.pid)) displayStatus = "stopped";
-		else if (r.log_file) {
-			const mtime = await stat(r.log_file).then((s) => s.mtimeMs).catch(() => null);
-			displayStatus = mtime !== null && Date.now() - mtime > IDLE_THRESHOLD_MS ? "idle" : "active";
-		} else displayStatus = "active";
+	const rows = await Promise.all(forestRows.map(async ({ record: r, prefix }) => {
+		const displayStatus = (await deriveLiveState(r)).state;
 		const note = notes.get(r.pid);
+		const tasks = displayStatus !== "stopped" && r.log_file ? await extractTaskCounts(r.log_file) : null;
+		const badge = tasks ? `${tasks.done}/${tasks.total} ` : "";
+		const budget = Math.max(8, promptBudget - prefix.length - badge.length);
 		let label;
 		let hasNote = false;
 		if (note) {
-			label = truncate(note, promptBudget);
+			label = truncate(note, budget);
 			hasNote = true;
-		} else if (r.log_file && displayStatus !== "stopped") label = truncate(await extractActivity(r.log_file) ?? (r.prompt ? `→ ${r.prompt}` : ""), promptBudget);
-		else label = truncate(r.prompt ? `→ ${r.prompt}` : "", promptBudget);
+		} else if (r.log_file && displayStatus !== "stopped") label = truncate(await extractActivity(r.log_file) ?? (r.prompt ? `→ ${r.prompt}` : ""), budget);
+		else label = truncate(r.prompt ? `→ ${r.prompt}` : "", budget);
+		label = prefix + (hasNote ? "* " : "") + badge + label;
 		return {
 			pid: String(r.pid),
 			cli: r.cli,
@@ -746,16 +1111,16 @@ async function cmdLs(rest) {
 		r.status.padEnd(widths.status),
 		r.age.padEnd(widths.age),
 		r.cwd.padEnd(widths.cwd),
-		r.hasNote ? `* ${r.label}` : r.label
+		r.label
 	].join("  ") + "\n");
 	if (!opts.json && rows.length > 0) {
 		const alive = rows.find((r) => r._alive);
 		const stopped = rows.find((r) => !r._alive);
 		const hints = ["\n"];
 		if (alive) {
-			hints.push(`  ay status ${alive.pid}                # JSON status snapshot\n`);
-			hints.push(`  ay status ${alive.pid} --watch        # stream changes as JSON\n`);
-			hints.push(`  ay status ${alive.pid} --wait-idle    # block until state == idle\n`);
+			hints.push(`  ay status ${alive.pid}                # JSON status snapshot (+ question)\n`);
+			hints.push(`  ay status ${alive.pid} --watch        # stream state changes as JSON\n`);
+			hints.push(`  ay status ${alive.pid} --wait         # block until it needs you (needs_input|idle|stopped)\n`);
 			hints.push(`  ay tail ${alive.pid}                  # view latest output\n`);
 			hints.push(`  ay tail -f ${alive.pid}               # follow live output\n`);
 			hints.push(`  ay send ${alive.pid} "next: ..."      # send a prompt (keyword: pid, cwd, or prompt substring)\n`);
@@ -1095,6 +1460,91 @@ async function extractActivity(logPath) {
 		return null;
 	}
 }
+/**
+* Extract the agent's current task progress ({done,total}) from its rendered TUI
+* screen — works for every CLI since the source is the drawn todo block, not a
+* CLI-specific session file. Reads a generous tail (the latest todo block can be
+* scrolled well back from the very last lines), renders the whole window through
+* xterm so reflow/redraw frames collapse to coherent text, then scans for the
+* most recent ⎿-anchored block. Returns null when none is confidently detected.
+*/
+async function extractTaskCounts(logPath) {
+	const TAIL_BYTES = 256 * 1024;
+	let buf;
+	try {
+		const fh = await open(logPath, "r");
+		try {
+			const { size } = await fh.stat();
+			if (size === 0) return null;
+			if (size <= TAIL_BYTES) {
+				const data = await fh.readFile();
+				buf = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+			} else {
+				const tmp = Buffer.alloc(TAIL_BYTES);
+				const { bytesRead } = await fh.read(tmp, 0, TAIL_BYTES, size - TAIL_BYTES);
+				buf = new Uint8Array(tmp.buffer, 0, bytesRead);
+			}
+		} finally {
+			await fh.close();
+		}
+	} catch {
+		return null;
+	}
+	try {
+		return parseTaskCounts((await renderRawLog(buf, {
+			mode: "cat",
+			n: 0
+		})).split("\n"));
+	} catch {
+		return null;
+	}
+}
+let _cliDefaults = null;
+function cliDefaults() {
+	return _cliDefaults ??= loadSharedCliDefaults().catch(() => ({}));
+}
+/**
+* Detect whether the agent is blocked on an interactive selection menu it didn't
+* auto-resolve (state `needs_input`). Reads the same 32 KB tail as extractActivity
+* and renders it through xterm, then runs the CLI's `needsInput`/`working`
+* patterns. Returns null when no menu is detected (or the CLI defines none).
+*/
+async function extractNeedsInput(logPath, cli) {
+	const cfg = (await cliDefaults())[cli];
+	if (!cfg?.needsInput?.length) return null;
+	const TAIL_BYTES = 32 * 1024;
+	let buf;
+	try {
+		const fh = await open(logPath, "r");
+		try {
+			const { size } = await fh.stat();
+			if (size === 0) return null;
+			if (size <= TAIL_BYTES) {
+				const data = await fh.readFile();
+				buf = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+			} else {
+				const tmp = Buffer.alloc(TAIL_BYTES);
+				const { bytesRead } = await fh.read(tmp, 0, TAIL_BYTES, size - TAIL_BYTES);
+				buf = new Uint8Array(tmp.buffer, 0, bytesRead);
+			}
+		} finally {
+			await fh.close();
+		}
+	} catch {
+		return null;
+	}
+	try {
+		return classifyNeedsInput((await renderRawLog(buf, {
+			mode: "tail",
+			n: 40
+		})).split("\n"), {
+			needsInput: cfg.needsInput,
+			working: cfg.working
+		});
+	} catch {
+		return null;
+	}
+}
 function extractActivityFromLines(lines) {
 	const isChrome = (l) => {
 		const s = l.trim();
@@ -1261,8 +1711,8 @@ async function writeToIpc(ipcPath, payload) {
 			});
 		});
 	} else {
-		const { openSync, writeFileSync, closeSync } = await import("fs");
-		const fd = openSync(ipcPath, "w");
+		const { openSync, writeFileSync, closeSync, constants } = await import("fs");
+		const fd = openSync(ipcPath, constants.O_WRONLY | constants.O_NONBLOCK);
 		try {
 			writeFileSync(fd, payload);
 		} finally {
@@ -1297,6 +1747,14 @@ async function cmdStop(rest) {
 	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 (!isPidAlive(record.pid)) {
+		await updateGlobalPidStatus(record.pid, {
+			status: "exited",
+			exit_reason: "already-stopped"
+		}).catch(() => {});
+		process.stdout.write(`pid ${record.pid} (${record.cli}) already stopped — marked exited\n`);
+		return 0;
+	}
 	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];
@@ -1572,6 +2030,14 @@ async function snapshotStatus(record) {
 		state = logMtimeMs !== null && Date.now() - logMtimeMs > IDLE_THRESHOLD_MS ? "idle" : "active";
 	} else state = "active";
 	const activity = state !== "stopped" && record.log_file ? await extractActivity(record.log_file) : null;
+	let question = null;
+	if (state !== "stopped" && record.log_file) {
+		const ni = await extractNeedsInput(record.log_file, record.cli);
+		if (ni) {
+			state = "needs_input";
+			question = ni.question;
+		}
+	}
 	const note = (await readNotes()).get(record.pid) ?? null;
 	return {
 		pid: record.pid,
@@ -1579,6 +2045,7 @@ async function snapshotStatus(record) {
 		cwd: record.cwd,
 		state,
 		activity,
+		question,
 		note,
 		log_mtime_ms: logMtimeMs,
 		started_at: record.started_at,
@@ -1594,13 +2061,17 @@ async function cmdStatus(rest) {
 		type: "boolean",
 		default: false,
 		description: "Stream changes as JSON"
+	}).option("wait", {
+		type: "boolean",
+		default: false,
+		description: "Block until the agent needs attention (needs_input | idle | stopped), then emit it. Exit 0 reached, 2 timeout. The JSON `state` says which — this is the primitive an orchestrator wants: it returns on a blocking question, not just on done."
 	}).option("wait-idle", {
 		type: "boolean",
 		default: false,
-		description: "Block until state == idle. Exit 0 idle, 1 stopped, 2 timeout"
+		description: "Block until state == idle. Exit 0 idle, 1 stopped, 2 timeout. Does NOT return on needs_input (a blocked menu) — use --wait for that."
 	}).option("timeout", {
 		type: "string",
-		description: "Timeout for --wait-idle (e.g. 30s, 5m). Default: no timeout"
+		description: "Timeout for --wait/--wait-idle (e.g. 30s, 5m). Default: no timeout"
 	}).option("interval", {
 		type: "number",
 		default: 2,
@@ -1621,12 +2092,13 @@ async function cmdStatus(rest) {
 		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
 	};
 	const keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
-	if (!keyword) throw new Error("usage: ay status <keyword> [--watch | --wait-idle] [--timeout=Ns]");
+	if (!keyword) throw new Error("usage: ay status <keyword> [--watch | --wait | --wait-idle] [--timeout=Ns]");
 	{
 		const remote = await resolveRemoteSpec(keyword);
 		if (remote) return runRemoteStatus(remote);
 	}
 	const watch = argv.watch;
+	const wait = argv.wait;
 	const waitIdle = argv["wait-idle"];
 	const intervalFlag = argv.interval;
 	const intervalMs = Math.max(500, (Number.isFinite(intervalFlag) ? intervalFlag : 2) * 1e3);
@@ -1640,6 +2112,21 @@ async function cmdStatus(rest) {
 		} : snap;
 		process.stdout.write(JSON.stringify(out) + "\n");
 	};
+	if (wait) {
+		const startedAt = Date.now();
+		for (;;) {
+			const snap = await snapshotStatus(record);
+			if (snap.state === "needs_input" || snap.state === "idle" || snap.state === "stopped") {
+				emit(snap);
+				return 0;
+			}
+			if (timeoutMs !== null && Date.now() - startedAt >= timeoutMs) {
+				emit(snap);
+				return 2;
+			}
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+	}
 	if (waitIdle) {
 		const startedAt = Date.now();
 		for (;;) {
@@ -1667,11 +2154,12 @@ async function cmdStatus(rest) {
 	let prev = null;
 	const tick = async () => {
 		const snap = await snapshotStatus(record);
-		if (prev === null || snap.state !== prev.state || snap.activity !== prev.activity || snap.exit_code !== prev.exit_code) {
+		if (prev === null || snap.state !== prev.state || snap.activity !== prev.activity || snap.question !== prev.question || snap.exit_code !== prev.exit_code) {
 			emit(snap, Date.now());
 			prev = {
 				state: snap.state,
 				activity: snap.activity,
+				question: snap.question,
 				exit_code: snap.exit_code
 			};
 		}
@@ -1686,7 +2174,134 @@ async function cmdStatus(rest) {
 	});
 	return 0;
 }
+/** Read all of stdin as a UTF-8 string (for `ay result set -` / piped JSON). */
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** Load a persisted result envelope, or null if none has been deposited yet. */
+async function loadStoredResult(pid) {
+	try {
+		const raw = await readFile(resultPath(pid), "utf8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+/**
+* `ay result` — two modes:
+*
+*   ay result set ['<json>' | -]   write side, run BY the agent. Keyed off the
+*                                  injected AGENT_YES_PID (or --pid N). Stores
+*                                  the envelope to ~/.agent-yes/results/<pid>.json.
+*
+*   ay result <keyword> [--wait]   read side, run by the parent. Resolves the
+*                                  agent and emits the stored envelope as JSON.
+*
+* Read-side exit codes (so an orchestrator can branch without parsing):
+*   0  envelope found and emitted
+*   1  agent stopped WITHOUT depositing one (it's done; there's no result)
+*   2  no envelope yet AND agent is still alive (pending) / --wait timed out
+*/
+async function cmdResult(rest) {
+	if (rest[0] === "set") return await cmdResultSet(rest.slice(1));
+	const argv = await yargs(rest).usage("Usage: ay result <keyword> [--wait] [--timeout Ns]").option("wait", {
+		type: "boolean",
+		default: false,
+		description: "Block until the agent deposits its result envelope (exit 0), or exits without one (exit 1), or --timeout elapses (exit 2)."
+	}).option("timeout", {
+		type: "string",
+		description: "Timeout for --wait (e.g. 30s, 5m)"
+	}).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 keyword = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	if (!keyword) throw new Error("usage: ay result <keyword> [--wait] | ay result set '<json>'");
+	const record = await resolveOne(keyword, {
+		all: true,
+		active: false,
+		json: false,
+		latest: argv.latest,
+		cwdScope: typeof argv.cwd === "string" ? path.resolve(argv.cwd) : null
+	});
+	const intervalMs = Math.max(500, (Number.isFinite(argv.interval) ? argv.interval : 2) * 1e3);
+	const timeoutMs = typeof argv.timeout === "string" && argv.timeout.length > 0 ? ms(argv.timeout) ?? NaN : null;
+	if (timeoutMs !== null && !Number.isFinite(timeoutMs)) throw new Error(`invalid --timeout value: ${argv.timeout}`);
+	const emitFound = (stored) => {
+		process.stdout.write(JSON.stringify({
+			pid: record.pid,
+			cli: record.cli,
+			cwd: record.cwd,
+			found: true,
+			written_at: stored.written_at,
+			result: stored.result
+		}) + "\n");
+	};
+	const emitMissing = (state) => {
+		process.stdout.write(JSON.stringify({
+			pid: record.pid,
+			cli: record.cli,
+			cwd: record.cwd,
+			found: false,
+			state
+		}) + "\n");
+	};
+	const startedAt = Date.now();
+	for (;;) {
+		const stored = await loadStoredResult(record.pid);
+		if (stored) {
+			emitFound(stored);
+			return 0;
+		}
+		const snap = await snapshotStatus(record);
+		if (snap.state === "stopped") {
+			const last = await loadStoredResult(record.pid);
+			if (last) {
+				emitFound(last);
+				return 0;
+			}
+			emitMissing("stopped");
+			return 1;
+		}
+		if (!argv.wait) {
+			emitMissing(snap.state);
+			return 2;
+		}
+		if (timeoutMs !== null && Date.now() - startedAt >= timeoutMs) {
+			emitMissing(snap.state);
+			return 2;
+		}
+		await new Promise((r) => setTimeout(r, intervalMs));
+	}
+}
+/** `ay result set [<json> | -]` — deposit THIS agent's envelope. */
+async function cmdResultSet(rest) {
+	const argv = await yargs(rest).usage("Usage: ay result set ['<json>' | -]").option("pid", {
+		type: "number",
+		description: "Target pid (default: $AGENT_YES_PID — the agent's own wrapper)"
+	}).help(false).version(false).exitProcess(false).parseAsync();
+	const pid = Number.isFinite(argv.pid) ? Number(argv.pid) : Number(process.env.AGENT_YES_PID);
+	if (!Number.isFinite(pid) || pid <= 0) throw new Error("ay result set: no target pid — run inside an ay-managed agent (AGENT_YES_PID is set) or pass --pid");
+	const positional = argv._[0] !== void 0 ? String(argv._[0]) : void 0;
+	const result = normalizeEnvelope(positional !== void 0 && positional !== "-" ? positional : await readStdin());
+	if (result === null) throw new Error("ay result set: empty input — pass a JSON object, text, or pipe via stdin");
+	await mkdir(resultsDir(), { recursive: true });
+	const stored = buildStoredResult(pid, result, Date.now());
+	await writeFile(resultPath(pid), JSON.stringify(stored) + "\n");
+	process.stdout.write(`result envelope written for pid ${pid}\n`);
+	return 0;
+}
 
 //#endregion
-export { finalizedLines as a, listRecords as c, renderRawLog as d, resolveOne as f, writeToIpc as g, stopTipForCli as h, cursorAbs as i, matchKeyword as l, snapshotStatus as m, cmdHelp as n, isPidAlive as o, runSubcommand as p, controlCodeFromName as r, isSubcommand as s, GRACEFUL_EXIT_COMMANDS as t, readNotes as u };
-//# sourceMappingURL=subcommands-CQowpr1t.js.map
+export { stopTipForCli as _, extractNeedsInput as a, isPidAlive as c, matchKeyword as d, readNotes as f, snapshotStatus as g, runSubcommand as h, cursorAbs as i, isSubcommand as l, resolveOne as m, cmdHelp as n, extractTaskCounts as o, renderRawLog as p, controlCodeFromName as r, finalizedLines as s, GRACEFUL_EXIT_COMMANDS as t, listRecords as u, writeToIpc as v };
+//# sourceMappingURL=subcommands-ClVHy-xI.js.map