claude-yes 1.167.0 → 1.169.0

package/dist/{ts-s3wYccKf.js → ts-DBYdQgbR.js}

@@ -1,7 +1,7 @@
 import { n as logger, t as addTransport } from "./logger-CDIsZ-Pp.js";
-import { r as getInstalledPackage } from "./versionChecker-BvR6tV3u.js";
+import { r as getInstalledPackage } from "./versionChecker-CL0RTOKo.js";
 import { t as agentYesHome } from "./agentYesHome-_eJa3DaX.js";
-import { i as shouldUseLock, r as releaseLock, t as acquireLock } from "./runningLock-V4qvXgAw.js";
+import { i as shouldUseLock, r as releaseLock, t as acquireLock } from "./runningLock-BobVW1_A.js";
 import { t as PidStore } from "./pidStore-BfoBWUjc.js";
 import { i as readGlobalPids } from "./globalPidIndex-DlmmJlO8.js";
 import { n as register, r as sweep } from "./reaper-C-eWAxIj.js";
@@ -289,8 +289,14 @@ var pty_default = pty;
 
 //#endregion
 //#region ts/removeControlCharacters.ts
+const ESC = String.fromCharCode(27);
+const C1 = String.fromCharCode(155);
+const BACKSLASH = String.fromCharCode(92);
+const ST_PATTERN_SOURCE = ESC + BACKSLASH + BACKSLASH;
+const OSC_PATTERN = new RegExp(ESC + "][^\x07\x1B]*(?:\x07|" + ST_PATTERN_SOURCE + ")", "g");
+const CSI_PATTERN = new RegExp("[" + ESC + C1 + "][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]", "g");
 function removeControlCharacters(str) {
-	return str.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, "");
+	return str.replace(OSC_PATTERN, "").replace(CSI_PATTERN, "");
 }
 
 //#endregion
@@ -474,6 +480,10 @@ var IdleWaiter = class {
 		this.lastActivityTime = Date.now();
 		return this;
 	}
+	/** Milliseconds since the last ping. */
+	idleTimeMs() {
+		return Date.now() - this.lastActivityTime;
+	}
 	async wait(ms) {
 		while (this.lastActivityTime >= Date.now() - ms) await new Promise((resolve) => setTimeout(resolve, this.checkInterval));
 	}
@@ -511,8 +521,12 @@ async function sendEnter(context, waitms = 1e3) {
 	logger.debug(`sendEnter| idleWait took ${String(Date.now() - st)}ms`);
 	context.nextStdout.unready();
 	context.shell.write("\r");
+	context.idleWaiter.ping();
 	for (const ms of [1e3, 3e3]) await Promise.race([context.nextStdout.wait(), new Promise((resolve) => setTimeout(() => {
-		if (!context.nextStdout.isReady) context.shell.write("\r");
+		if (!context.nextStdout.isReady) {
+			context.shell.write("\r");
+			context.idleWaiter.ping();
+		}
 		resolve();
 	}, ms))]);
 }
@@ -543,11 +557,21 @@ async function sendMessage(context, message, { waitForReady = true } = {}) {
 const AUTO_RETRY_BASE_SECS = 8;
 const AUTO_RETRY_MAX_DELAY_SECS = 256;
 const AUTO_RETRY_GIVE_UP_MS = 8 * 3600 * 1e3;
+const AUTO_RETRY_MIN_IDLE_MS = 5e3;
 /** Backoff (ms) before the Nth consecutive auto-retry — doubles, then caps. */
 function autoRetryBackoffMs(streak) {
 	const shift = Math.min(streak, 20);
 	return Math.min(AUTO_RETRY_BASE_SECS * 2 ** shift, AUTO_RETRY_MAX_DELAY_SECS) * 1e3;
 }
+/**
+* Whether a scheduled auto-retry may actually fire: the agent must be sitting
+* idle at a ready prompt (not mid-work) AND the terminal must have been quiet
+* for at least `minIdleMs` — see AUTO_RETRY_MIN_IDLE_MS. Mirrors Rust's
+* should_fire_retry in rs/src/context.rs.
+*/
+function shouldFireRetry(working, ready, idleMs, minIdleMs) {
+	return !working && ready && idleMs >= minIdleMs;
+}
 
 //#endregion
 //#region ts/core/logging.ts
@@ -1503,17 +1527,13 @@ async function agentYes({ cli, cliArgs = [], skipPermissions = false, prompt, ro
 					retryNextAt = null;
 					retryStartedAt = null;
 					retryStreak = 0;
-				} else if (now >= retryNextAt) {
-					const working = conf.working?.some((rx) => rx.test(autoRetryScreen)) ?? false;
-					const readyNow = conf.ready?.some((rx) => rx.test(autoRetryScreen)) ?? false;
-					if (working || !readyNow) retryNextAt = now + 500;
-					else {
-						retryStreak += 1;
-						logger.warn(`[${cli}-yes] auto-retry: typing 'retry' (attempt ${retryStreak})`);
-						ctx.messageContext.shell.write("retry\r");
-						ctx.idleWaiter.ping();
-						retryNextAt = now + autoRetryBackoffMs(retryStreak);
-					}
+				} else if (now >= retryNextAt) if (!shouldFireRetry(conf.working?.some((rx) => rx.test(autoRetryScreen)) ?? false, conf.ready?.some((rx) => rx.test(autoRetryScreen)) ?? false, ctx.idleWaiter.idleTimeMs(), AUTO_RETRY_MIN_IDLE_MS)) retryNextAt = now + 500;
+				else {
+					retryStreak += 1;
+					logger.warn(`[${cli}-yes] auto-retry: typing 'retry' (attempt ${retryStreak})`);
+					ctx.messageContext.shell.write("retry\r");
+					ctx.idleWaiter.ping();
+					retryNextAt = now + autoRetryBackoffMs(retryStreak);
 				}
 			}
 			if (rendered === lastHeartbeatRendered) return;
@@ -1689,10 +1709,11 @@ async function agentYes({ cli, cliArgs = [], skipPermissions = false, prompt, ro
 		writable: new WritableStream({ write: async (data) => {
 			await ctx.stdinReady.wait();
 			shell.write(data);
+			ctx.idleWaiter.ping();
 		} }),
 		readable: xtermProxy.readable
-	}).forEach(() => {
-		ctx.idleWaiter.ping();
+	}).forEach((chunk) => {
+		if (removeControlCharacters(chunk).trim()) ctx.idleWaiter.ping();
 		pidStore.updateStatus(shell.pid, "active").catch(() => null);
 		ctx.nextStdout.ready();
 	}).forkTo(async function rawLogger(f) {
@@ -1803,4 +1824,4 @@ function sleep(ms) {
 
 //#endregion
 export { removeControlCharacters as a, AgentContext as i, agentYes as n, config as r, CLIS_CONFIG as t };
-//# sourceMappingURL=ts-s3wYccKf.js.map
+//# sourceMappingURL=ts-DBYdQgbR.js.map

package/dist/{versionChecker-BvR6tV3u.js → versionChecker-CL0RTOKo.js}

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

package/dist/{webrtcLink-CBZkZ-LT.js → webrtcLink-BG0Xc4-W.js}

@@ -1,4 +1,4 @@
-import { u as parseSecret } from "./e2e-Bfw7qL9O.js";
+import { u as parseSecret } from "./e2e-BeKjLhmO.js";
 
 //#region ts/webrtcLink.ts
 const SIGNAL_SUBPROTOCOL = "ay-signal-1";
@@ -42,4 +42,4 @@ function isWebrtcSpec(spec) {
 
 //#endregion
 export { isWebrtcSpec as n, parseWebrtcLink as r, SIGNAL_SUBPROTOCOL as t };
-//# sourceMappingURL=webrtcLink-CBZkZ-LT.js.map
+//# sourceMappingURL=webrtcLink-BG0Xc4-W.js.map

package/dist/{webrtcRemote-GAgF5K45.js → webrtcRemote-SybKurg9.js}

@@ -1,5 +1,5 @@
-import { a as computeTranscriptHash, c as open, d as randomHex, f as seal, l as packEnvelope, n as FLAG_CONFIRM, o as deriveAuthToken, p as unpackEnvelope, s as deriveDirKeys } from "./e2e-Bfw7qL9O.js";
-import { n as isWebrtcSpec, r as parseWebrtcLink, t as SIGNAL_SUBPROTOCOL } from "./webrtcLink-CBZkZ-LT.js";
+import { a as computeTranscriptHash, c as open, d as randomHex, f as seal, l as packEnvelope, n as FLAG_CONFIRM, o as deriveAuthToken, p as unpackEnvelope, s as deriveDirKeys } from "./e2e-BeKjLhmO.js";
+import { n as isWebrtcSpec, r as parseWebrtcLink, t as SIGNAL_SUBPROTOCOL } from "./webrtcLink-BG0Xc4-W.js";
 import { RTCPeerConnection } from "node-datachannel/polyfill";
 
 //#region ts/webrtcRemote.ts
@@ -256,4 +256,4 @@ async function startWebrtcBridge(link) {
 
 //#endregion
 export { startWebrtcBridge };
-//# sourceMappingURL=webrtcRemote-GAgF5K45.js.map
+//# sourceMappingURL=webrtcRemote-SybKurg9.js.map

package/dist/{workspaceConfig-D3OH7and.js → workspaceConfig-BC03X4Y1.js}

@@ -162,4 +162,4 @@ function resolveSpawnCwd(input) {
 
 //#endregion
 export { getSpawnWaitMs as a, isProvisionAllowed as c, getSpawnHook as i, resolveSpawnCwd as l, getMinFreeMb as n, getWorkspaceRoot as o, getProvisionRoot as r, hasSpawnHook as s, getMaxAgents as t, setWorkspaceRoot as u };
-//# sourceMappingURL=workspaceConfig-D3OH7and.js.map
+//# sourceMappingURL=workspaceConfig-BC03X4Y1.js.map

package/lab/ui/console-logic.js

@@ -180,6 +180,22 @@ export function taskLabel(e) {
   return `${t.done}/${t.total}`;
 }
 
+// Display metadata for status flags matched server-side against an agent's
+// screen (ts/badges.ts BADGE_DEFS — matching runs server-side; the API sends
+// just the matched ids in e.badges). Keep the label/title text here in sync
+// with ts/badges.ts. An id with no entry still renders (falls back to the raw
+// id), so a newly-added server-side badge is never silently dropped.
+export const BADGE_META = {
+  "goal-active": { label: "goal", title: "A /goal Stop-hook loop is active on this agent" },
+};
+
+// Status-flag chips ("badges") matched against the agent's screen — e.g. an
+// active /goal loop. [] when e.badges is missing/empty. Returns
+// { id, label, title } objects ready for the caller to render as chips.
+export function badgesFor(e) {
+  return (e.badges || []).map((id) => ({ id, ...(BADGE_META[id] || { label: id, title: id }) }));
+}
+
 // Human age of an agent ("12s" / "5m" / "3h"). `now` is injectable so tests
 // don't depend on the wall clock; the browser calls age(e) and gets Date.now().
 export function age(e, now = Date.now()) {

package/lab/ui/index.html

@@ -891,6 +891,20 @@
         color: var(--green);
         border-color: #2a3a2a;
       }
+      /* Status-flag chip ("badge") matched server-side against the agent's
+         screen — e.g. an active /goal loop (ts/badges.ts). Same pill shape as
+         .tasks but accent-colored so a matched flag stands out as a distinct
+         signal, not just a counter. */
+      .flag {
+        font-family: var(--mono);
+        font-size: 10.5px;
+        color: var(--accent);
+        white-space: nowrap;
+        flex: none;
+        padding: 0 5px;
+        border: 1px solid var(--accent);
+        border-radius: 8px;
+      }
       /* The pending question when an agent needs_input — blue accent to match the
          needs_input dot, reading as "your turn / here's what it's asking". */
       .detail.ask {
@@ -1543,6 +1557,7 @@
         sortEntries,
         SORT_MODES,
         taskLabel,
+        badgesFor,
         hashHue,
         selFromBottom,
         parseSel,
@@ -3219,6 +3234,17 @@
         return `<span class="tasks${allDone ? " done" : ""}" title="${esc(tip)}">${esc(label)}</span>`;
       }
 
+      // Status-flag chips ("badges") matched server-side against the agent's
+      // screen (ts/badges.ts) — e.g. an active /goal loop. One small pill per
+      // matched flag; "" when none matched. CSS class is "flag" (not "badge")
+      // to avoid colliding with the existing pid pill's .badge class. See
+      // BADGE_META in console-logic.js for the id → label/title mapping.
+      function badgeChipsHtml(e) {
+        return badgesFor(e)
+          .map((b) => `<span class="flag" title="${esc(b.title)}">${esc(b.label)}</span>`)
+          .join("");
+      }
+
       // A room/peer group header row. Non-selectable; carries the same tree rails
       // as agent rows so the hierarchy reads as one tree. The room/peer layers
       // only appear here when there are ≥2 of them (single ones fold away in
@@ -3268,6 +3294,7 @@
         ${cli ? `<span class="cname">${esc(cli)}</span>` : ""}
         <span class="ctitle ${e.title ? "" : "dim"}" title="${esc(t)}">${esc(t)}</span>
         ${taskChipHtml(e)}
+        ${badgeChipsHtml(e)}
         ${gitChipHtml(e)}
         <span class="age">${age(e)}</span></div>`;
               })
@@ -3293,6 +3320,7 @@
           <span class="name">${esc(cliLabel(e) || ident(e) || "agent")}</span>
           <span class="badge">pid ${e.pid}</span>
           ${taskChipHtml(e)}
+          ${badgeChipsHtml(e)}
           ${gitChipHtml(e)}
           <span class="age">${age(e)}</span></div>
         ${e.title ? `<div class="rowtitle" title="${esc(e.title)}">${esc(e.title)}</div>` : ""}

package/package.json

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

package/ts/autoRetry.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { AUTO_RETRY_MAX_DELAY_SECS, autoRetryBackoffMs } from "./autoRetry.ts";
+import { AUTO_RETRY_MAX_DELAY_SECS, autoRetryBackoffMs, shouldFireRetry } from "./autoRetry.ts";
 
 describe("autoRetryBackoffMs", () => {
   it("doubles 8,16,32,…,256 then caps", () => {
@@ -17,3 +17,18 @@ describe("autoRetryBackoffMs", () => {
     expect(Number.isFinite(autoRetryBackoffMs(1000))).toBe(true);
   });
 });
+
+describe("shouldFireRetry", () => {
+  it("requires ready + not working + past the idle window", () => {
+    // Busy — never fire even if otherwise ready and quiet.
+    expect(shouldFireRetry(true, true, 10_000, 5_000)).toBe(false);
+    // Not at a recognized ready prompt — don't fire.
+    expect(shouldFireRetry(false, false, 10_000, 5_000)).toBe(false);
+    // Ready and idle, but the quiet window hasn't elapsed yet (user may still
+    // be mid-typing) — defer.
+    expect(shouldFireRetry(false, true, 4_999, 5_000)).toBe(false);
+    // Ready, idle, and past the quiet window — fire.
+    expect(shouldFireRetry(false, true, 5_000, 5_000)).toBe(true);
+    expect(shouldFireRetry(false, true, 10_000, 5_000)).toBe(true);
+  });
+});

package/ts/autoRetry.ts

@@ -8,9 +8,32 @@ export const AUTO_RETRY_BASE_SECS = 8; // first backoff; doubles each consecutiv
 export const AUTO_RETRY_MAX_DELAY_SECS = 256; // cap: 8,16,32,…,256 then hold
 export const AUTO_RETRY_GIVE_UP_MS = 8 * 3600 * 1000; // stop after 8h (claude's usage window is ~5h)
 
+// Minimum quiet time (no CLI output, no forwarded stdin — see idleWaiter.ping()
+// call sites) required before a scheduled auto-retry may actually fire, on top
+// of the backoff delay above. The backoff schedule alone can elapse while the
+// user is mid-typing into the prompt; typing "retry" + Enter over that would
+// submit a mangled line. Deliberately short — this only debounces against
+// active typing, not a real excuse to delay recovery.
+export const AUTO_RETRY_MIN_IDLE_MS = 5_000;
+
 /** Backoff (ms) before the Nth consecutive auto-retry — doubles, then caps. */
 export function autoRetryBackoffMs(streak: number): number {
   const shift = Math.min(streak, 20); // guard against absurd streaks blowing up 2 ** n
   const secs = Math.min(AUTO_RETRY_BASE_SECS * 2 ** shift, AUTO_RETRY_MAX_DELAY_SECS);
   return secs * 1000;
 }
+
+/**
+ * Whether a scheduled auto-retry may actually fire: the agent must be sitting
+ * idle at a ready prompt (not mid-work) AND the terminal must have been quiet
+ * for at least `minIdleMs` — see AUTO_RETRY_MIN_IDLE_MS. Mirrors Rust's
+ * should_fire_retry in rs/src/context.rs.
+ */
+export function shouldFireRetry(
+  working: boolean,
+  ready: boolean,
+  idleMs: number,
+  minIdleMs: number,
+): boolean {
+  return !working && ready && idleMs >= minIdleMs;
+}

package/ts/badges.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { badgeDef, BADGE_DEFS, matchBadges, type BadgeDef } from "./badges.ts";
+
+describe("matchBadges", () => {
+  it("matches goal-active when the /goal status line is on screen", () => {
+    const lines = ["some output", "/goal active (42s)", "more output"];
+    expect(matchBadges(lines)).toEqual(["goal-active"]);
+  });
+
+  it("is case-insensitive", () => {
+    expect(matchBadges(["/GOAL ACTIVE (1s)"])).toEqual(["goal-active"]);
+  });
+
+  it("returns empty when nothing matches", () => {
+    expect(matchBadges(["just some regular CLI output", "nothing special here"])).toEqual([]);
+  });
+
+  it("returns empty for an empty screen", () => {
+    expect(matchBadges([])).toEqual([]);
+  });
+
+  it("matches across a join boundary between lines (pattern spans the joined text)", () => {
+    // Sanity: matchBadges joins lines with \n before testing, so a pattern that
+    // doesn't care about line boundaries still finds a hit split across two lines.
+    const defs: BadgeDef[] = [{ id: "spans", label: "x", title: "t", pattern: /foo\nbar/ }];
+    expect(matchBadges(["foo", "bar"], defs)).toEqual(["spans"]);
+  });
+
+  it("supports custom def sets independent of the built-in BADGE_DEFS", () => {
+    const defs: BadgeDef[] = [
+      { id: "custom-error", label: "err", title: "custom error banner", pattern: /FATAL: boom/ },
+    ];
+    expect(matchBadges(["FATAL: boom"], defs)).toEqual(["custom-error"]);
+    expect(matchBadges(["FATAL: boom"])).toEqual([]); // not in the default set
+  });
+
+  it("can match multiple badges at once, in def order", () => {
+    const defs: BadgeDef[] = [
+      { id: "a", label: "a", title: "a", pattern: /alpha/ },
+      { id: "b", label: "b", title: "b", pattern: /beta/ },
+    ];
+    expect(matchBadges(["alpha and beta both here"], defs)).toEqual(["a", "b"]);
+  });
+});
+
+describe("badgeDef", () => {
+  it("looks up a built-in definition by id", () => {
+    expect(badgeDef("goal-active")).toBe(BADGE_DEFS[0]);
+  });
+
+  it("returns undefined for an unknown id", () => {
+    expect(badgeDef("does-not-exist")).toBeUndefined();
+  });
+});

package/ts/badges.ts

@@ -0,0 +1,42 @@
+/**
+ * Badge/flag matchers: small regex patterns run against an agent's last
+ * rendered screen (the same tail window `ay tail` shows — see
+ * extractBadges in subcommands.ts) to surface a short status chip in the
+ * web console's agent list. Extensible: add more entries to BADGE_DEFS as
+ * useful patterns turn up (a known error banner, a loop-state flag, etc.).
+ * Pure and CLI-agnostic — a definition just won't match on CLIs that never
+ * print its pattern.
+ */
+
+export interface BadgeDef {
+  /** Stable id, used as the wire value and as the key when re-deriving the label. */
+  id: string;
+  /** Short chip text, e.g. "goal". Keep it a couple of characters — the chip is tiny. */
+  label: string;
+  /** Tooltip shown on hover, explaining what the badge means. */
+  title: string;
+  /** Matched against the tail-rendered screen text (lines joined with \n). */
+  pattern: RegExp;
+}
+
+export const BADGE_DEFS: BadgeDef[] = [
+  {
+    id: "goal-active",
+    label: "goal",
+    title: "A /goal Stop-hook loop is active on this agent",
+    pattern: /\/goal active/i,
+  },
+];
+
+/**
+ * Which badge ids match the given rendered screen lines. Pure so it's
+ * unit-tested without a live PTY/log file.
+ */
+export function matchBadges(lines: string[], defs: BadgeDef[] = BADGE_DEFS): string[] {
+  const text = lines.join("\n");
+  return defs.filter((d) => d.pattern.test(text)).map((d) => d.id);
+}
+
+export function badgeDef(id: string, defs: BadgeDef[] = BADGE_DEFS): BadgeDef | undefined {
+  return defs.find((d) => d.id === id);
+}

package/ts/cli.ts

@@ -106,6 +106,52 @@ if (config.useRust) {
       console.log(`[rust] Args: ${rustArgs.join(" ")}`);
     }
 
+    // Nested + non-tty (e.g. an agent ran this via its Bash tool): detach the
+    // agent so we don't block the parent's tool call for the whole session, then
+    // print how to drive it and exit. `--attach`/AGENT_YES_ATTACH=1 opts out.
+    const attach = config.attach || process.env.AGENT_YES_ATTACH === "1";
+    const { shouldForkNested, buildSpawnTutorial, waitForFifo } = await import("./forkNested.ts");
+    if (
+      shouldForkNested({
+        isTTY: Boolean(process.stdout.isTTY),
+        ayPid: process.env.AGENT_YES_PID,
+        attach,
+      })
+    ) {
+      const forked = spawn(rustBinary, rustArgs, {
+        detached: true,
+        stdio: "ignore",
+        env: process.env,
+        cwd: process.cwd(),
+      });
+      const forkedPid = forked.pid;
+      if (!forkedPid) {
+        console.error("Failed to spawn agent: no pid.");
+        process.exit(1);
+      }
+      // Race a fast startup failure against FIFO registration so we never print a
+      // success tutorial for a dead pid. The wrapper keeps its own per-pid log, so
+      // real output stays reachable via `ay tail` even with stdio ignored. Store a
+      // pre-formatted message (not a union) — the callbacks run async, so control-flow
+      // analysis can't narrow a union here anyway.
+      let deathMsg: string | null = null;
+      forked.on("error", (err) => {
+        deathMsg ??= `Failed to spawn agent: ${err.message}`;
+      });
+      forked.on("exit", (code, signal) => {
+        deathMsg ??= `Agent exited immediately (${signal ?? `code ${code}`}). See: ay tail ${forkedPid}`;
+      });
+      const registered = await waitForFifo(forkedPid, 2000, () => deathMsg !== null);
+      if (deathMsg) {
+        console.error(deathMsg);
+        process.exit(1);
+      }
+      forked.unref();
+      console.log(buildSpawnTutorial(config.cli || "agent", forkedPid));
+      if (!registered) console.log(`(note: still registering — give ay send/tail a moment)`);
+      process.exit(0);
+    }
+
     const child = spawn(rustBinary, rustArgs, {
       stdio: "inherit",
       env: process.env,

package/ts/forkNested.spec.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { buildSpawnTutorial, shouldForkNested } from "./forkNested";
+
+describe("shouldForkNested", () => {
+  it("forks when nested (AGENT_YES_PID set) and stdout is not a TTY", () => {
+    expect(shouldForkNested({ isTTY: false, ayPid: "1234", attach: false })).toBe(true);
+  });
+
+  it("does NOT fork on an interactive TTY (a human running it directly)", () => {
+    expect(shouldForkNested({ isTTY: true, ayPid: "1234", attach: false })).toBe(false);
+  });
+
+  it("does NOT fork when not nested — a human piping output has no AGENT_YES_PID", () => {
+    expect(shouldForkNested({ isTTY: false, ayPid: undefined, attach: false })).toBe(false);
+    expect(shouldForkNested({ isTTY: false, ayPid: "", attach: false })).toBe(false);
+    expect(shouldForkNested({ isTTY: false, ayPid: "   ", attach: false })).toBe(false);
+  });
+
+  it("does NOT fork when attach opts out, regardless of context", () => {
+    expect(shouldForkNested({ isTTY: false, ayPid: "1234", attach: true })).toBe(false);
+  });
+});
+
+describe("buildSpawnTutorial", () => {
+  it("names the cli + pid and lists the drive commands with that pid", () => {
+    const out = buildSpawnTutorial("claude", 4242);
+    expect(out).toContain("Spawned claude agent as pid 4242");
+    expect(out).toContain("ay tail 4242");
+    expect(out).toContain("ay send 4242");
+    expect(out).toContain("ay ls");
+    expect(out).toContain("ay result get 4242");
+    expect(out).toContain("ay exit 4242");
+  });
+});

package/ts/forkNested.ts

@@ -0,0 +1,64 @@
+import { existsSync } from "fs";
+import path from "path";
+import { agentYesHome } from "./agentYesHome.ts";
+
+/**
+ * Should a nested agent-run detach (fork) instead of blocking the caller?
+ *
+ * A claude/codex agent that runs `ay <cli> -- <task>` inside its Bash tool would
+ * otherwise block that Bash call for the whole (possibly very long) session and
+ * time out. When we detect that context we spawn the agent detached, print a
+ * tutorial, and return immediately so the parent stays responsive.
+ *
+ * The context is: we are NESTED inside another agent (`AGENT_YES_PID` is injected
+ * into an agent's environment by its wrapper — a human shell never has it) AND
+ * stdout is not a TTY (captured/piped, e.g. a tool's Bash). A human piping output
+ * (`ay claude | cat`) has no `AGENT_YES_PID`, so they still block as before.
+ * `attach` (the `--attach` flag or `AGENT_YES_ATTACH=1`) forces foreground.
+ */
+export function shouldForkNested(opts: {
+  isTTY: boolean;
+  ayPid: string | undefined;
+  attach: boolean;
+}): boolean {
+  if (opts.attach) return false;
+  if (opts.isTTY) return false;
+  return Boolean(opts.ayPid && opts.ayPid.trim());
+}
+
+/** The tutorial printed to the parent agent after a detached spawn, telling it
+ *  exactly how to drive the agent it just started. */
+export function buildSpawnTutorial(cli: string, pid: number): string {
+  return [
+    `Spawned ${cli} agent as pid ${pid} (detached — this shell returned immediately).`,
+    `It runs in the background; drive it with:`,
+    `  ay tail ${pid}          # watch its output (live)`,
+    `  ay send ${pid} "..."    # send it a message / instruction`,
+    `  ay send ${pid} /compact # send a slash command`,
+    `  ay ls                   # list running agents`,
+    `  ay result get ${pid}    # read its final result when done`,
+    `  ay exit ${pid}          # stop it`,
+  ].join("\n");
+}
+
+/**
+ * Poll for the spawned wrapper's stdin FIFO to appear, so the tutorial's
+ * `ay send`/`ay tail` work the instant we print them (the wrapper registers its
+ * FIFO a moment after spawn). Resolves true once registered, false on timeout or
+ * if `aborted()` reports the child already died (so a startup failure fails fast
+ * instead of waiting out the whole window).
+ */
+export async function waitForFifo(
+  pid: number,
+  timeoutMs = 2000,
+  aborted?: () => boolean,
+): Promise<boolean> {
+  const fifo = path.join(agentYesHome(), "fifo", `${pid}.stdin`);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (aborted?.()) return false;
+    if (existsSync(fifo)) return true;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return existsSync(fifo);
+}

package/ts/idleWaiter.spec.ts

@@ -59,6 +59,18 @@ describe("IdleWaiter", () => {
     expect(result).toBe(waiter);
   });
 
+  it("idleTimeMs reflects elapsed time since the last ping", async () => {
+    const waiter = new IdleWaiter();
+    waiter.ping();
+    expect(waiter.idleTimeMs()).toBeLessThan(20);
+
+    await new Promise((r) => setTimeout(r, 50));
+    expect(waiter.idleTimeMs()).toBeGreaterThanOrEqual(50);
+
+    waiter.ping();
+    expect(waiter.idleTimeMs()).toBeLessThan(20);
+  });
+
   it("should wait until idle period has passed", async () => {
     const waiter = new IdleWaiter();
     waiter.checkInterval = 10;

package/ts/idleWaiter.ts

@@ -24,6 +24,11 @@ export class IdleWaiter {
     return this;
   }
 
+  /** Milliseconds since the last ping. */
+  idleTimeMs() {
+    return Date.now() - this.lastActivityTime;
+  }
+
   async wait(ms: number) {
     while (this.lastActivityTime >= Date.now() - ms)
       await new Promise((resolve) => setTimeout(resolve, this.checkInterval));

package/ts/index.ts

@@ -18,7 +18,12 @@ import { logger } from "./logger.ts";
 import { createFifoStream } from "./beta/fifo.ts";
 import { PidStore } from "./pidStore.ts";
 import { sendEnter, sendMessage } from "./core/messaging.ts";
-import { AUTO_RETRY_GIVE_UP_MS, autoRetryBackoffMs } from "./autoRetry.ts";
+import {
+  AUTO_RETRY_GIVE_UP_MS,
+  AUTO_RETRY_MIN_IDLE_MS,
+  autoRetryBackoffMs,
+  shouldFireRetry,
+} from "./autoRetry.ts";
 import {
   initializeLogPaths,
   setupDebugLogging,
@@ -805,8 +810,12 @@ export default async function agentYes({
         } else if (now >= retryNextAt) {
           const working = conf.working?.some((rx: RegExp) => rx.test(autoRetryScreen)) ?? false;
           const readyNow = conf.ready?.some((rx: RegExp) => rx.test(autoRetryScreen)) ?? false;
-          if (working || !readyNow) {
-            retryNextAt = now + 500; // busy / not at prompt — re-check shortly
+          // Also require a few quiet seconds on top of the backoff delay, so a
+          // scheduled retry doesn't collide with a line the user is actively
+          // typing into the prompt (see AUTO_RETRY_MIN_IDLE_MS).
+          const idleMs = ctx.idleWaiter.idleTimeMs();
+          if (!shouldFireRetry(working, readyNow, idleMs, AUTO_RETRY_MIN_IDLE_MS)) {
+            retryNextAt = now + 500; // busy / not at prompt / still active — re-check shortly
           } else {
             retryStreak += 1;
             logger.warn(`[${cli}-yes] auto-retry: typing 'retry' (attempt ${retryStreak})`);
@@ -1096,13 +1105,22 @@ export default async function agentYes({
         write: async (data) => {
           await ctx.stdinReady.wait();
           shell.write(data);
+          // Forwarded user input counts as activity too (mirrors the Rust
+          // runtime's ping on stdin forward) — the auto-retry idle gate below
+          // must not fire while the user is actively typing.
+          ctx.idleWaiter.ping();
         },
       }),
       readable: xtermProxy.readable,
     })
 
-    .forEach(() => {
-      ctx.idleWaiter.ping();
+    .forEach((chunk) => {
+      // Only ping activity if there's visible content (not just ANSI/cursor
+      // control sequences) — mirrors the Rust runtime's handle_output gate.
+      // Without this, periodic control-only chatter (e.g. cursor position
+      // queries) would keep resetting the auto-retry idle clock and the
+      // scheduled retry could defer indefinitely without ever firing.
+      if (removeControlCharacters(chunk).trim()) ctx.idleWaiter.ping();
       pidStore.updateStatus(shell.pid, "active").catch(() => null);
       ctx.nextStdout.ready();
     })