agent-yes 1.196.3 → 1.198.0

package/dist/ws-BpHPhcPH.js

@@ -0,0 +1,399 @@
+import "./logger-CDIsZ-Pp.js";
+import "./globalPidIndex-CoNr7tS8.js";
+import "./messageLog-CxrKJj77.js";
+import "./configShared-aKTg-sa5.js";
+import { S as listRecords } from "./subcommands-D7AmlO_6.js";
+import "./e2e-jb0Hp43q.js";
+import "./webrtcLink-B7REGtK2.js";
+import "./remotes-Cim0dBU7.js";
+import { i as getProvisionRoot } from "./workspaceConfig-CjaRvTjf.js";
+import { existsSync } from "fs";
+import { lstat, opendir } from "fs/promises";
+import path from "path";
+
+//#region ts/ws.ts
+/**
+* `ay ws` — workspace management over the codehost/provision standard layout
+* (`<wsRoot>/<owner>/<repo>/tree/<branch>`, independent clones except forked
+* linked worktrees).
+*
+* v1 surface (read/list/new/fork only — deletion/gc/doctor are deliberately
+* deferred until workspace lifecycle data exists to design them around):
+*
+*   ay ws ls [--status] [--json]
+*   ay ws status [<spec-or-path>] [--path|--spec] [--json]
+*   ay ws new <source> [--create]
+*   ay ws fork <branch> [--from <path>] [--wip]
+*
+* `--json` schema (stable, versioned via `schema`):
+*   ls:     { schema:"ay-ws/v1", wsRoot, workspaces: WsEntry[] }
+*   status: { schema:"ay-ws/v1", workspace: WsEntry }
+*   WsEntry = { owner, repo, branch, path, agents: { live: number },
+*               git?: GitStatus | null, gitError?: string }
+*
+* codehost/provision is a peer package (bun-linked in dev). Like serve.ts's
+* fork path, it is imported lazily so `ay ls` etc. never pay for it and a
+* missing install produces a clear actionable error instead of a module crash.
+*/
+async function loadProvision() {
+	try {
+		return await import("codehost/provision");
+	} catch (e) {
+		throw new Error(`'ay ws' needs the 'codehost' package (codehost/provision) — install it (npm i -g codehost) or 'bun link' it for local dev: ${e.message}`);
+	}
+}
+const WS_JSON_SCHEMA = "ay-ws/v1";
+const STATUS_CONCURRENCY = 8;
+const MAX_BRANCH_DEPTH = 8;
+/**
+* Path containment that matches how the OS actually compares paths: segment
+* boundaries via path.relative (never a raw startsWith), case-insensitive on
+* Windows (and macOS's default case-insensitive FS is fine with this too —
+* false positives there require two dirs differing only by case).
+*/
+function isPathInside(parent, child) {
+	let p = path.resolve(parent);
+	let c = path.resolve(child);
+	if (process.platform === "win32") {
+		p = p.toLowerCase();
+		c = c.toLowerCase();
+	}
+	const rel = path.relative(p, c);
+	return rel === "" || !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/** True when `dir` is a git checkout root (`.git` file = linked worktree, dir = clone). */
+function isCheckoutRoot(dir) {
+	return existsSync(path.join(dir, ".git"));
+}
+async function subdirs(dir) {
+	const out = [];
+	let d;
+	try {
+		d = await opendir(dir);
+	} catch {
+		return out;
+	}
+	for await (const ent of d) {
+		if (ent.name.startsWith(".")) continue;
+		if (ent.isDirectory()) out.push(ent.name);
+		else if (ent.isSymbolicLink()) continue;
+	}
+	return out.sort();
+}
+/**
+* Walk `<wsRoot>/<owner>/<repo>/tree/**` collecting checkout roots. The branch
+* may contain `/`, so below `tree/` we descend until a `.git` marker is found
+* (a checkout root is never nested inside another checkout in this layout),
+* bounded by MAX_BRANCH_DEPTH.
+*/
+async function walkWorkspaces(wsRoot) {
+	const found = [];
+	async function walkBranches(dir, owner, repo, segs) {
+		if (segs.length > MAX_BRANCH_DEPTH) return;
+		for (const name of await subdirs(dir)) {
+			const p = path.join(dir, name);
+			const branchSegs = [...segs, name];
+			if (isCheckoutRoot(p)) found.push({
+				owner,
+				repo,
+				branch: branchSegs.join("/"),
+				path: p
+			});
+			else await walkBranches(p, owner, repo, branchSegs);
+		}
+	}
+	for (const owner of await subdirs(wsRoot)) for (const repo of await subdirs(path.join(wsRoot, owner))) {
+		const tree = path.join(wsRoot, owner, repo, "tree");
+		try {
+			if (!(await lstat(tree)).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		await walkBranches(tree, owner, repo, []);
+	}
+	return found;
+}
+/** Live (non-exited) agents whose cwd sits inside `wsPath`. */
+function liveAgentsIn(records, wsPath) {
+	return records.filter((r) => r.cwd && isPathInside(wsPath, r.cwd));
+}
+async function mapBounded(items, limit, fn) {
+	const out = new Array(items.length);
+	let next = 0;
+	const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+		while (next < items.length) {
+			const i = next++;
+			out[i] = await fn(items[i]);
+		}
+	});
+	await Promise.all(workers);
+	return out;
+}
+/**
+* Resolve a status/inspect operand deterministically:
+*   1. `--path` forces path, `--spec` forces source-spec parsing
+*   2. an operand that exists on disk is a path
+*   3. otherwise it must parse as a source (owner/repo[@branch|/tree/branch] or URL)
+* Prints the normalized resolution so the user always sees what was addressed.
+*/
+async function resolveOperand(prov, operand, mode, wsRoot) {
+	const asPath = () => {
+		const dir = path.resolve(operand);
+		if (!existsSync(dir)) throw new Error(`path does not exist: ${dir}`);
+		if (!isCheckoutRoot(dir)) throw new Error(`not a git checkout root (no .git): ${dir}`);
+		return {
+			dir,
+			spec: null
+		};
+	};
+	const asSpec = () => {
+		const spec = prov.parseSource(operand);
+		if (!spec) throw new Error(`cannot parse "${operand}" as a source — expected <owner>/<repo>, <owner>/<repo>@<branch>, <owner>/<repo>/tree/<branch>, or a github URL` + (existsSync(operand) ? "" : " (and it is not an existing path)"));
+		const dir = prov.folderFor(spec, wsRoot);
+		if (!existsSync(dir)) throw new Error(`workspace not provisioned: ${dir}  (ay ws new ${operand})`);
+		return {
+			dir,
+			spec
+		};
+	};
+	if (mode === "path") return asPath();
+	if (mode === "spec") return asSpec();
+	if (existsSync(path.resolve(operand))) return asPath();
+	return asSpec();
+}
+/**
+* Default source for `ws fork`: the calling agent's registered cwd when run
+* inside an agent (AGENT_YES_PID is the wrapper pid of the enclosing agent),
+* else the current directory.
+*/
+async function defaultForkFrom() {
+	const envPid = Number(process.env.AGENT_YES_PID);
+	if (envPid > 0) {
+		const recs = await listRecords(void 0, {
+			all: true,
+			active: false,
+			json: false,
+			latest: false,
+			cwdScope: null
+		});
+		const self = recs.find((r) => r.wrapper_pid === envPid) ?? recs.find((r) => r.pid === envPid);
+		if (self?.cwd) return self.cwd;
+	}
+	return process.cwd();
+}
+function parseFlags(args, known) {
+	const flags = {};
+	const positional = [];
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (!a.startsWith("--")) {
+			positional.push(a);
+			continue;
+		}
+		const eq = a.indexOf("=");
+		const name = eq === -1 ? a.slice(2) : a.slice(2, eq);
+		const kind = known[name];
+		if (!kind) throw new Error(`unknown flag --${name}`);
+		if (kind === "bool") {
+			if (eq !== -1) throw new Error(`--${name} takes no value`);
+			flags[name] = true;
+		} else {
+			const v = eq !== -1 ? a.slice(eq + 1) : args[++i];
+			if (v === void 0) throw new Error(`--${name} requires a value`);
+			flags[name] = v;
+		}
+	}
+	return {
+		flags,
+		positional
+	};
+}
+async function cmdWsLs(args) {
+	const { flags, positional } = parseFlags(args, {
+		status: "bool",
+		json: "bool"
+	});
+	if (positional.length > 0) throw new Error(`ws ls takes no positional args`);
+	const prov = await loadProvision();
+	const wsRoot = prov.resolveWsRoot(getProvisionRoot());
+	const [bare, records] = await Promise.all([walkWorkspaces(wsRoot), listRecords(void 0, {
+		all: false,
+		active: false,
+		json: false,
+		latest: false,
+		cwdScope: null
+	})]);
+	let entries = bare.map((w) => ({
+		...w,
+		agents: { live: liveAgentsIn(records, w.path).length }
+	}));
+	if (flags.status) entries = await mapBounded(entries, STATUS_CONCURRENCY, async (e) => {
+		try {
+			return {
+				...e,
+				git: await prov.readStatus(e.path)
+			};
+		} catch (err) {
+			return {
+				...e,
+				git: null,
+				gitError: err.message.slice(0, 200)
+			};
+		}
+	});
+	if (flags.json) {
+		process.stdout.write(JSON.stringify({
+			schema: WS_JSON_SCHEMA,
+			wsRoot,
+			workspaces: entries
+		}, null, 2) + "\n");
+		return 0;
+	}
+	if (entries.length === 0) {
+		process.stderr.write(`no workspaces under ${wsRoot} (layout <owner>/<repo>/tree/<branch>)\n`);
+		return 0;
+	}
+	const specOf = (e) => `${e.owner}/${e.repo}@${e.branch}`;
+	const specW = Math.max(9, ...entries.map((e) => specOf(e).length));
+	const agentsW = 6;
+	const header = flags.status ? `${"WORKSPACE".padEnd(specW)}  ${"AGENTS".padEnd(agentsW)}  GIT\n` : `${"WORKSPACE".padEnd(specW)}  ${"AGENTS".padEnd(agentsW)}  PATH\n`;
+	process.stdout.write(header);
+	for (const e of entries) {
+		const agents = e.agents.live > 0 ? String(e.agents.live) : "-";
+		const tail = flags.status ? gitSummary(e) : e.path;
+		process.stdout.write(`${specOf(e).padEnd(specW)}  ${agents.padEnd(agentsW)}  ${tail}\n`);
+	}
+	if (entries.some((e) => e.agents.live > 0)) process.stderr.write(`\n  ay ls --cwd <path>    # the agents inside a workspace\n`);
+	return 0;
+}
+function gitSummary(e) {
+	if (e.gitError) return `error: ${e.gitError}`;
+	const g = e.git;
+	if (!g) return "?";
+	const parts = [];
+	if (g.dirty) parts.push("dirty");
+	if (g.ahead > 0) parts.push(`ahead ${g.ahead}`);
+	if (g.behind > 0) parts.push(`behind ${g.behind}`);
+	if (!g.hasUpstream) parts.push("no-upstream");
+	return parts.length ? parts.join(", ") : "clean";
+}
+async function cmdWsStatus(args) {
+	const { flags, positional } = parseFlags(args, {
+		json: "bool",
+		path: "bool",
+		spec: "bool"
+	});
+	if (flags.path && flags.spec) throw new Error("--path and --spec are mutually exclusive");
+	if (positional.length > 1) throw new Error("ws status takes at most one target");
+	const prov = await loadProvision();
+	const wsRoot = getProvisionRoot();
+	const { dir, spec } = await resolveOperand(prov, positional[0] ?? ".", flags.path ? "path" : flags.spec ? "spec" : "auto", wsRoot);
+	const git = await prov.readStatus(dir);
+	const layoutSpec = spec ?? (() => {
+		const root = prov.resolveWsRoot(wsRoot);
+		if (!isPathInside(root, dir)) return null;
+		const segs = path.relative(root, dir).split(path.sep);
+		return segs.length >= 4 && segs[2] === "tree" ? {
+			owner: segs[0],
+			repo: segs[1],
+			branch: segs.slice(3).join("/")
+		} : null;
+	})();
+	const entry = {
+		owner: layoutSpec?.owner ?? "",
+		repo: layoutSpec?.repo ?? "",
+		branch: layoutSpec?.branch ?? git.branch,
+		path: dir,
+		agents: { live: liveAgentsIn(await listRecords(void 0, {
+			all: false,
+			active: false,
+			json: false,
+			latest: false,
+			cwdScope: null
+		}), dir).length },
+		git
+	};
+	if (flags.json) {
+		process.stdout.write(JSON.stringify({
+			schema: WS_JSON_SCHEMA,
+			workspace: entry
+		}, null, 2) + "\n");
+		return 0;
+	}
+	process.stdout.write(`${dir}\n` + (layoutSpec ? `  spec:     ${layoutSpec.owner}/${layoutSpec.repo}@${layoutSpec.branch}\n` : "") + `  branch:   ${git.branch} @ ${git.head}\n  state:    ${gitSummary(entry)}\n  agents:   ${entry.agents.live} live\n`);
+	if (entry.agents.live > 0) process.stderr.write(`\n  ay ls --cwd ${dir}\n`);
+	return 0;
+}
+async function cmdWsNew(args) {
+	const { flags, positional } = parseFlags(args, { create: "bool" });
+	const source = positional[0];
+	if (!source || positional.length > 1) throw new Error("usage: ay ws new <owner>/<repo>[@branch] [--create]");
+	const prov = await loadProvision();
+	const wsRoot = getProvisionRoot();
+	const spec = prov.parseSource(source);
+	if (!spec) throw new Error(`cannot parse "${source}" as a source (owner/repo[@branch] or URL)`);
+	process.stderr.write(`provisioning ${spec.owner}/${spec.repo}@${spec.branch} …\n`);
+	let res = await prov.provision(spec, { wsRoot });
+	if (!res.ok && res.reason === "branch-not-found" && flags.create) {
+		process.stderr.write(`branch not found on remote — creating it locally (--create)\n`);
+		res = await prov.createBranch(spec, { wsRoot });
+	}
+	if (!res.ok) {
+		process.stderr.write(`provision failed (${res.reason ?? "error"}): ${res.error ?? "unknown"}\n` + (res.reason === "branch-not-found" && !flags.create ? `  (branch missing on the remote — re-run with --create to branch off the default)\n` : ""));
+		return 1;
+	}
+	process.stdout.write(`${res.action}  ${res.folder}\n`);
+	return 0;
+}
+async function cmdWsFork(args) {
+	const { flags, positional } = parseFlags(args, {
+		from: "value",
+		wip: "bool"
+	});
+	const branch = positional[0];
+	if (!branch || positional.length > 1) throw new Error("usage: ay ws fork <new-branch> [--from <path>] [--wip]");
+	const prov = await loadProvision();
+	const fromCwd = path.resolve(typeof flags.from === "string" ? flags.from : await defaultForkFrom());
+	process.stderr.write(`forking ${fromCwd} → branch ${branch}${flags.wip ? " (with WIP)" : ""} …\n`);
+	const res = await prov.forkWorktree({
+		fromCwd,
+		branch,
+		wsRoot: getProvisionRoot(),
+		wip: !!flags.wip
+	});
+	if (!res.ok) {
+		process.stderr.write(`fork failed: ${res.error ?? "unknown"}\n`);
+		return 1;
+	}
+	process.stdout.write(`${res.action}  ${res.folder}\n`);
+	process.stderr.write(`\n  ay claude --cwd ${res.folder} -- "<prompt>"   # work there\n`);
+	return 0;
+}
+function wsHelp() {
+	process.stdout.write("ay ws - workspaces under <wsRoot>/<owner>/<repo>/tree/<branch>\n\n  ay ws ls [--status] [--json]           list workspaces (+git state, +live agent count)\n  ay ws status [<spec|path>] [--json]    one workspace's git state (default: cwd)\n  ay ws new <owner>/<repo>[@branch]      clone/refresh a workspace  (--create: new branch)\n  ay ws fork <branch> [--from <path>]    sibling worktree off HEAD  (--wip: carry changes)\n\n  targets: owner/repo, owner/repo@branch, owner/repo/tree/branch, github URL, or a path\n  wsRoot:  CODEHOST_WS_ROOT > config provisionRoot > ~/ws\n");
+	return 0;
+}
+/** `ay ws <sub> …` dispatcher (called from runSubcommand). */
+async function cmdWs(args) {
+	const sub = args[0];
+	const rest = args.slice(1);
+	switch (sub) {
+		case "ls":
+		case "list": return cmdWsLs(rest);
+		case "status": return cmdWsStatus(rest);
+		case "new": return cmdWsNew(rest);
+		case "fork": return cmdWsFork(rest);
+		case void 0:
+		case "help":
+		case "--help":
+		case "-h": return wsHelp();
+		default:
+			process.stderr.write(`ay ws: unknown subcommand "${sub}"\n\n`);
+			wsHelp();
+			return 1;
+	}
+}
+
+//#endregion
+export { cmdWs };
+//# sourceMappingURL=ws-BpHPhcPH.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-yes",
-  "version": "1.196.3",
+  "version": "1.198.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,15 @@
 import { describe, expect, it } from "vitest";
-import { AUTO_RETRY_MAX_DELAY_SECS, autoRetryBackoffMs, shouldFireRetry } from "./autoRetry.ts";
+import {
+  AUTO_RETRY_MAX_DELAY_SECS,
+  AUTO_RETRY_REASON_FALLBACK,
+  AUTO_RETRY_REASONS,
+  autoRetryBackoffMs,
+  buildAutoRetryMessage,
+  classifyAutoRetryReason,
+  formatDurationSecs,
+  shouldFireRetry,
+} from "./autoRetry.ts";
+import { loadSharedCliDefaults } from "./configShared.ts";
 
 describe("autoRetryBackoffMs", () => {
   it("doubles 8,16,32,…,256 then caps", () => {
@@ -32,3 +42,82 @@ describe("shouldFireRetry", () => {
     expect(shouldFireRetry(false, true, 10_000, 5_000)).toBe(true);
   });
 });
+
+describe("classifyAutoRetryReason", () => {
+  it("maps real banners to inert paraphrases", () => {
+    expect(classifyAutoRetryReason("● API Error: 529 Overloaded")).toBe(AUTO_RETRY_REASONS[0]);
+    expect(classifyAutoRetryReason("API Error: Response stalled mid-stream.")).toBe(
+      AUTO_RETRY_REASONS[1],
+    );
+    expect(classifyAutoRetryReason("API Error: Connection closed mid-response.")).toBe(
+      AUTO_RETRY_REASONS[2],
+    );
+    expect(classifyAutoRetryReason("Claude usage limit reached")).toBe(AUTO_RETRY_REASONS[3]);
+    expect(classifyAutoRetryReason("You are being rate-limited")).toBe(AUTO_RETRY_REASONS[4]);
+    expect(classifyAutoRetryReason("API Error: 503 Service Unavailable")).toBe(
+      AUTO_RETRY_REASON_FALLBACK,
+    );
+  });
+});
+
+describe("formatDurationSecs", () => {
+  it("renders s / m / h forms", () => {
+    expect(formatDurationSecs(0)).toBe("0s");
+    expect(formatDurationSecs(45)).toBe("45s");
+    expect(formatDurationSecs(60)).toBe("1m");
+    expect(formatDurationSecs(200)).toBe("3m20s");
+    expect(formatDurationSecs(3600)).toBe("1h");
+    expect(formatDurationSecs(3900)).toBe("1h05m");
+    expect(formatDurationSecs(8 * 3600)).toBe("8h");
+  });
+});
+
+describe("buildAutoRetryMessage", () => {
+  it("is one line and carries attempt/reason/backoff context + ignore clause", () => {
+    const msg = buildAutoRetryMessage(3, AUTO_RETRY_REASONS[0], 45, 64);
+    expect(msg).not.toContain("\n");
+    expect(msg.startsWith("retry [")).toBe(true);
+    expect(msg).toContain("#3");
+    expect(msg).toContain("45s ago");
+    expect(msg).toContain("in 1m04s");
+    expect(msg).toContain("giving up after 8h");
+    expect(msg).toContain("ignore it");
+  });
+
+  // Self-trigger guard: the message is typed into the PTY and stays visible in
+  // the transcript, so if it ever matched a CLI's own screen-scrape patterns
+  // it would re-arm the retry loop (autoRetry), block the streak reset, kill
+  // the session (fatal), or fake a state (working/enter/needsInput). Mirrors
+  // rs/src/config.rs test_auto_retry_message_is_inert_against_all_cli_patterns.
+  it("never matches any CLI's screen-scrape patterns", async () => {
+    const clis = await loadSharedCliDefaults();
+    expect(Object.keys(clis).length).toBeGreaterThan(0);
+    for (const [cliName, conf] of Object.entries(clis)) {
+      for (const reason of AUTO_RETRY_REASONS) {
+        const cases: [number, number, number][] = [
+          [1, 0, 8],
+          [5, 500, 128],
+          [12, 30_000, 256],
+        ];
+        for (const [attempt, since, next] of cases) {
+          const msg = buildAutoRetryMessage(attempt, reason, since, next);
+          const groups: [string, RegExp[] | undefined][] = [
+            ["autoRetry", conf.autoRetry],
+            ["fatal", conf.fatal],
+            ["enter", conf.enter],
+            ["working", conf.working],
+            ["needsInput", conf.needsInput],
+          ];
+          for (const [kind, patterns] of groups) {
+            for (const rx of patterns ?? []) {
+              expect(
+                rx.test(msg),
+                `retry message must not match ${cliName}.${kind} /${rx}/: ${msg}`,
+              ).toBe(false);
+            }
+          }
+        }
+      }
+    }
+  });
+});

package/ts/autoRetry.ts

@@ -37,3 +37,79 @@ export function shouldFireRetry(
 ): boolean {
   return !working && ready && idleMs >= minIdleMs;
 }
+
+/** Fallback reason when no autoRetry match was captured before firing. */
+export const AUTO_RETRY_REASON_FALLBACK = "a transient server-side error";
+
+/**
+ * All reason strings `classifyAutoRetryReason` can produce — used by the
+ * self-trigger guard spec to prove every possible typed message is inert
+ * against every CLI's screen-scrape patterns. Mirrors Rust's RETRY_REASONS.
+ */
+export const AUTO_RETRY_REASONS = [
+  "the model backend reported it is temporarily busy",
+  "the response stream stalled mid-way",
+  "the connection dropped mid-response",
+  "a usage cap was reached (it may need time to reset)",
+  "requests are being throttled by the server",
+  AUTO_RETRY_REASON_FALLBACK,
+] as const;
+
+/**
+ * Paraphrase the matched recoverable-error banner into a short reason.
+ *
+ * Deliberately NEVER echoes the raw banner wording ("API Error", "Overloaded",
+ * "rate limit", …): the built message is typed into the PTY and stays visible
+ * in the transcript, where raw wording would re-match the autoRetry patterns —
+ * keeping the error state true forever, which blocks the streak reset on
+ * recovery. Mirrors Rust's classify_retry_reason.
+ */
+export function classifyAutoRetryReason(screen: string): string {
+  const s = screen.toLowerCase();
+  if (s.includes("overload")) return AUTO_RETRY_REASONS[0];
+  if (s.includes("stalled")) return AUTO_RETRY_REASONS[1];
+  if (s.includes("connection closed")) return AUTO_RETRY_REASONS[2];
+  if (s.includes("usage limit") || s.includes("session limit")) return AUTO_RETRY_REASONS[3];
+  if (s.includes("rate") && s.includes("limit")) return AUTO_RETRY_REASONS[4];
+  return AUTO_RETRY_REASON_FALLBACK;
+}
+
+/** Human-readable duration: "45s", "3m20s", "1h04m", "8h". Mirrors Rust's fmt_dur_secs. */
+export function formatDurationSecs(total: number): string {
+  const t = Math.max(0, Math.floor(total));
+  if (t < 60) return `${t}s`;
+  if (t < 3600) {
+    const m = Math.floor(t / 60);
+    const s = t % 60;
+    return s === 0 ? `${m}m` : `${m}m${String(s).padStart(2, "0")}s`;
+  }
+  const h = Math.floor(t / 3600);
+  const m = Math.floor((t % 3600) / 60);
+  return m === 0 ? `${h}h` : `${h}h${String(m).padStart(2, "0")}m`;
+}
+
+/**
+ * The single line typed into the agent's prompt instead of a bare "retry":
+ * says WHO is nudging (agent-yes, automated), WHY (paraphrased reason), and
+ * the backoff state (attempt #, elapsed, next delay, give-up horizon), plus an
+ * explicit "ignore if nothing failed" clause so an agent that already
+ * recovered — or is mid-question — doesn't burn a turn asking what "retry"
+ * refers to. Must stay one line (it is submitted with a single "\r").
+ * Mirrors Rust's build_retry_message in rs/src/context.rs.
+ */
+export function buildAutoRetryMessage(
+  attempt: number,
+  reason: string,
+  sinceFirstSecs: number,
+  nextBackoffSecs: number,
+): string {
+  const since = formatDurationSecs(sinceFirstSecs);
+  const next = formatDurationSecs(nextBackoffSecs);
+  const giveUp = formatDurationSecs(AUTO_RETRY_GIVE_UP_MS / 1000);
+  return (
+    `retry [auto-retry #${attempt} by agent-yes: ${reason}; first seen ${since} ago; ` +
+    `if this attempt fails too, the next nudge comes in ${next} (giving up after ${giveUp}). ` +
+    `This is an automated recovery nudge - if no request actually failed, ignore it and ` +
+    `simply continue your previous task.]`
+  );
+}

package/ts/index.ts

@@ -21,9 +21,14 @@ import { sendEnter, sendMessage } from "./core/messaging.ts";
 import {
   AUTO_RETRY_GIVE_UP_MS,
   AUTO_RETRY_MIN_IDLE_MS,
+  AUTO_RETRY_REASON_FALLBACK,
   autoRetryBackoffMs,
+  buildAutoRetryMessage,
+  classifyAutoRetryReason,
+  formatDurationSecs,
   shouldFireRetry,
 } from "./autoRetry.ts";
+import { recordInbox } from "./messageLog.ts";
 import {
   initializeLogPaths,
   setupDebugLogging,
@@ -794,6 +799,9 @@ export default async function agentYes({
   let retryStartedAt: number | null = null;
   let retryNextAt: number | null = null;
   let autoRetryScreen = "";
+  // Paraphrased reason captured when the error banner was matched — folded
+  // into the typed retry message so the agent knows why it is being nudged.
+  let retryReason: string | null = null;
   const heartbeatInterval = setInterval(async () => {
     try {
       const rendered = removeControlCharacters(xtermProxy.tail(12));
@@ -822,15 +830,36 @@ export default async function agentYes({
             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})`);
-            // Write "retry" + Enter atomically (mirrors rs do_send_retry); using
+            const nextBackoffMs = autoRetryBackoffMs(retryStreak);
+            const reason = retryReason ?? AUTO_RETRY_REASON_FALLBACK;
+            const sinceFirstSecs = retryStartedAt === null ? 0 : (now - retryStartedAt) / 1000;
+            const line = buildAutoRetryMessage(
+              retryStreak,
+              reason,
+              sinceFirstSecs,
+              nextBackoffMs / 1000,
+            );
+            logger.warn(
+              `[${cli}-yes] auto-retry: typing retry nudge (attempt ${retryStreak}, reason: ${reason})`,
+            );
+            // Write the nudge + Enter atomically (mirrors rs do_send_retry); using
             // sendMessage would split text/Enter across the fast heartbeat ticks.
-            ctx.messageContext.shell.write("retry\r");
+            ctx.messageContext.shell.write(line + "\r");
             ctx.idleWaiter.ping();
+            // Structured trace for `ay msgs` / the console (mirrors the Rust
+            // runtime's record_auto_retry_inbox) — best-effort, never blocks.
+            void recordInbox({
+              at: now,
+              from: null,
+              to: { pid: process.pid, cli, cwd: workingDir },
+              kind: "auto-retry",
+              body: `${reason} (attempt ${retryStreak}, next backoff ${formatDurationSecs(nextBackoffMs / 1000)})`,
+              wrapped: false,
+            });
             // Self-schedule the next retry with escalated backoff. (Leaving nextAt
             // null and re-arming from the stdout pipeline would tight-loop while the
             // error banner stays on screen.) Reset on recovery cancels this.
-            retryNextAt = now + autoRetryBackoffMs(retryStreak);
+            retryNextAt = now + nextBackoffMs;
           }
         }
       }
@@ -1185,6 +1214,10 @@ export default async function agentYes({
               const errVisible = conf.autoRetry.some((rx: RegExp) => rx.test(rendered));
               const readyVisible = conf.ready?.some((rx: RegExp) => rx.test(rendered)) ?? false;
               if (errVisible && readyVisible) {
+                // Remember WHY (paraphrased — see classifyAutoRetryReason) so
+                // the typed message can explain itself. Refresh on every match:
+                // the banner may change across attempts (e.g. overload → 5xx).
+                retryReason = classifyAutoRetryReason(rendered);
                 if (retryNextAt === null) {
                   if (retryStartedAt === null) retryStartedAt = Date.now();
                   const delayMs = autoRetryBackoffMs(retryStreak);

package/ts/messageLog.ts

@@ -39,8 +39,9 @@ export interface MessageRecord {
   to: MailParty;
   /** What kind of stdin write this was. Omitted for a normal `ay send` text
    * message; "key" for raw keystrokes (`ay key`), "select" for a menu pick
-   * (`ay select`). For key/select the `body` holds the key names / choice. */
-  kind?: "key" | "select";
+   * (`ay select`), "auto-retry" for the wrapper's own recoverable-error nudge
+   * (from is null; `body` holds the paraphrased reason + backoff state). */
+  kind?: "key" | "select" | "auto-retry";
   /** The message body (without the `[ay-msg …]` wrapper), or — for a key/select
    * record — the keystroke names / chosen option. */
   body: string;