agent-yes 1.121.0 → 1.122.1

package/dist/workspaceConfig-XP2NEWmV.js

@@ -0,0 +1,56 @@
+import { t as agentYesHome } from "./agentYesHome-BvaUOzCV.js";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+
+//#region ts/workspaceConfig.ts
+function configPath() {
+	return path.join(agentYesHome(), "config.json");
+}
+function readConfig() {
+	try {
+		return JSON.parse(readFileSync(configPath(), "utf-8"));
+	} catch {
+		return {};
+	}
+}
+/** Expand a leading `~` (`~` or `~/x`) to an absolute home-based path. */
+function expandTilde(p) {
+	const s = p.trim();
+	if (s === "~") return homedir();
+	if (s.startsWith("~/") || s.startsWith("~\\")) return path.join(homedir(), s.slice(2));
+	return s;
+}
+/** The configured workspace root (absolute), or the home dir if unset. */
+function getWorkspaceRoot() {
+	const w = readConfig().workspace;
+	return w && w.trim() ? w : homedir();
+}
+/** Persist the workspace root, tilde-expanded and resolved to an absolute path. */
+function setWorkspaceRoot(dir) {
+	const abs = path.resolve(expandTilde(dir));
+	const cfg = readConfig();
+	cfg.workspace = abs;
+	mkdirSync(agentYesHome(), { recursive: true });
+	writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+	return abs;
+}
+/**
+* Resolve a user-supplied spawn location to an absolute cwd:
+* - empty            → the workspace root
+* - a bare name      → `<workspace>/<name>` (so "myproject" lands under the root)
+* - `~`-prefixed     → home-based absolute
+* - anything with a path separator → resolved as-is
+*/
+function resolveSpawnCwd(input) {
+	const root = getWorkspaceRoot();
+	const v = (input ?? "").trim();
+	if (!v) return root;
+	if (v.startsWith("~")) return path.resolve(expandTilde(v));
+	if (v.includes("/") || v.includes("\\") || path.isAbsolute(v)) return path.resolve(v);
+	return path.join(root, v);
+}
+
+//#endregion
+export { resolveSpawnCwd as n, setWorkspaceRoot as r, getWorkspaceRoot as t };
+//# sourceMappingURL=workspaceConfig-XP2NEWmV.js.map

package/lab/ui/index.html

@@ -990,38 +990,45 @@
               if (m.type === "welcome") {
                 if (this._v2 && m.v !== 2)
                   return fail(new Error("host is running an old agent-yes — ask it to upgrade"));
-                pc = new RTCPeerConnection({
-                  iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
-                });
-                this.pc = pc;
-                pc.onicecandidate = (e) => {
-                  if (e.candidate)
-                    ws.send(JSON.stringify({ type: "candidate", candidate: e.candidate }));
-                };
-                pc.onconnectionstatechange = () => this.onstate(pc.connectionState);
-                pc.ondatachannel = (e) => {
-                  this.dc = e.channel;
-                  this.dc.binaryType = "arraybuffer";
-                  this.dc.onopen = async () => {
-                    try {
-                      await this._keysReady;
-                      // Open the bidirectional confirmation handshake.
-                      this._dcSend(FLAG_CONFIRM, { t: "confirm", nonce: this._myNonce });
-                      this._confirmTimer = setTimeout(() => {
-                        if (!this._confirmed) fail(new Error("key confirmation timed out"));
-                      }, CONFIRM_TIMEOUT_MS);
-                    } catch (err) {
-                      fail(err);
-                    }
+                // pc is created on the offer below so it can use the host-supplied
+                // iceServers (incl. short-lived TURN creds for relaying behind NAT).
+              } else if (m.type === "offer") {
+                if (!pc) {
+                  pc = new RTCPeerConnection({
+                    iceServers:
+                      m.iceServers && m.iceServers.length
+                        ? m.iceServers
+                        : [{ urls: "stun:stun.l.google.com:19302" }],
+                  });
+                  this.pc = pc;
+                  pc.onicecandidate = (e) => {
+                    if (e.candidate)
+                      ws.send(JSON.stringify({ type: "candidate", candidate: e.candidate }));
                   };
-                  this.dc.onmessage = (ev2) => {
-                    this._recvChain = this._recvChain
-                      .then(() => this._dcRecv(ev2.data, done))
-                      .catch(() => {});
+                  pc.onconnectionstatechange = () => this.onstate(pc.connectionState);
+                  pc.ondatachannel = (e) => {
+                    this.dc = e.channel;
+                    this.dc.binaryType = "arraybuffer";
+                    this.dc.onopen = async () => {
+                      try {
+                        await this._keysReady;
+                        // Open the bidirectional confirmation handshake.
+                        this._dcSend(FLAG_CONFIRM, { t: "confirm", nonce: this._myNonce });
+                        this._confirmTimer = setTimeout(() => {
+                          if (!this._confirmed) fail(new Error("key confirmation timed out"));
+                        }, CONFIRM_TIMEOUT_MS);
+                      } catch (err) {
+                        fail(err);
+                      }
+                    };
+                    this.dc.onmessage = (ev2) => {
+                      this._recvChain = this._recvChain
+                        .then(() => this._dcRecv(ev2.data, done))
+                        .catch(() => {});
+                    };
+                    this.dc.onclose = () => this.onstate("closed");
                   };
-                  this.dc.onclose = () => this.onstate("closed");
-                };
-              } else if (m.type === "offer") {
+                }
                 await pc.setRemoteDescription({ type: "offer", sdp: m.sdp });
                 await pc.setLocalDescription(await pc.createAnswer());
                 ws.send(JSON.stringify({ type: "answer", sdp: pc.localDescription.sdp }));
@@ -1040,7 +1047,7 @@
                   fail(err);
                 }
               } else if (m.type === "candidate") {
-                await pc.addIceCandidate(m.candidate).catch(() => {});
+                if (pc) await pc.addIceCandidate(m.candidate).catch(() => {});
               }
             };
             ws.onerror = () => fail(new Error("signaling error"));
@@ -2346,9 +2353,33 @@
           cwd: $("nf-cwd").value.trim(),
           prompt: $("nf-prompt").value,
         };
+        const room = $("newform").dataset.room || undefined;
+        // Warn (but allow) when an agent is already running in this cwd on the
+        // target fleet. A 2nd `claude -c` in the same repo fights over the same
+        // session/files and usually exits on startup — which looks like "the new
+        // agent never appears". Let the user pick a different dir or proceed.
+        if (spec.cwd) {
+          await loadList();
+          const norm = (p) => (p || "").replace(/\/+$/, "");
+          const busy = entries.some(
+            (e) =>
+              (room ? e._room === room : true) &&
+              e.exit_code == null &&
+              norm(e.cwd) === norm(spec.cwd),
+          );
+          if (
+            busy &&
+            !confirm(
+              `An agent is already running in:\n${spec.cwd}\n\n` +
+                `Launching another in the same repo can collide (shared session/files) ` +
+                `and the new one may exit immediately. Launch anyway?`,
+            )
+          )
+            return;
+        }
         go.disabled = true;
         go.textContent = "launching…";
-        const ok = await spawnAndSelect(spec, $("newform").dataset.room || undefined);
+        const ok = await spawnAndSelect(spec, room);
         if (ok) {
           $("newform").style.display = "none";
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-yes",
-  "version": "1.121.0",
+  "version": "1.122.1",
   "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

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { AUTO_RETRY_MAX_DELAY_SECS, autoRetryBackoffMs } from "./autoRetry.ts";
+
+describe("autoRetryBackoffMs", () => {
+  it("doubles 8,16,32,…,256 then caps", () => {
+    expect(autoRetryBackoffMs(0)).toBe(8_000);
+    expect(autoRetryBackoffMs(1)).toBe(16_000);
+    expect(autoRetryBackoffMs(2)).toBe(32_000);
+    expect(autoRetryBackoffMs(3)).toBe(64_000);
+    expect(autoRetryBackoffMs(4)).toBe(128_000);
+    expect(autoRetryBackoffMs(5)).toBe(256_000);
+  });
+
+  it("caps at the max delay and never overflows for large streaks", () => {
+    expect(autoRetryBackoffMs(6)).toBe(AUTO_RETRY_MAX_DELAY_SECS * 1000);
+    expect(autoRetryBackoffMs(50)).toBe(AUTO_RETRY_MAX_DELAY_SECS * 1000);
+    expect(Number.isFinite(autoRetryBackoffMs(1000))).toBe(true);
+  });
+});

package/ts/autoRetry.ts

@@ -0,0 +1,16 @@
+// Auto-retry on recoverable API errors (overload / rate-limit / usage-limit):
+// agent-yes types "retry" with exponential backoff instead of letting the run
+// die. This module holds the backoff schedule shared by the heartbeat logic and
+// its tests. It mirrors the Rust runtime — see rs/src/context.rs
+// (retry_backoff_secs / RETRY_* constants) — keep the two in sync.
+
+export const AUTO_RETRY_BASE_SECS = 8; // first backoff; doubles each consecutive failure
+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)
+
+/** 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;
+}

package/ts/configShared.ts

@@ -17,6 +17,7 @@ type RawCliConfig = Omit<
   | "restartWithoutContinueArg"
   | "updateAvailable"
   | "exitCommands"
+  | "autoRetry"
 > & {
   ready?: RegexSource[];
   fatal?: RegexSource[];
@@ -26,6 +27,7 @@ type RawCliConfig = Omit<
   typingRespond?: Record<string, RegexSource[]>;
   restartWithoutContinueArg?: RegexSource[];
   updateAvailable?: RegexSource[];
+  autoRetry?: RegexSource[];
   exitCommands?: string[];
   exitCommand?: string[];
 };
@@ -78,6 +80,7 @@ export function normalizeCliConfig(raw: RawCliConfig): AgentCliConfig {
     typingRespond,
     restartWithoutContinueArg,
     updateAvailable,
+    autoRetry,
     exitCommands,
     exitCommand,
     ...rest
@@ -93,6 +96,7 @@ export function normalizeCliConfig(raw: RawCliConfig): AgentCliConfig {
     typingRespond: compileTypingRespond(typingRespond),
     restartWithoutContinueArg: compileRegexList(restartWithoutContinueArg),
     updateAvailable: compileRegexList(updateAvailable),
+    autoRetry: compileRegexList(autoRetry),
     exitCommands: exitCommands ?? exitCommand,
   };
 }

package/ts/index.ts

@@ -18,6 +18,7 @@ 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 {
   initializeLogPaths,
   setupDebugLogging,
@@ -30,6 +31,7 @@ import { createTerminatorStream } from "./core/streamHelpers.ts";
 import { globalAgentRegistry } from "./agentRegistry.ts";
 import { notifyWebhook } from "./webhookNotifier.ts";
 import { readGlobalPids } from "./globalPidIndex.ts";
+import * as reaper from "./reaper.ts";
 
 export { removeControlCharacters };
 export { AgentContext };
@@ -62,6 +64,7 @@ export type AgentCliConfig = {
   enter?: RegExp[]; // array of regex to match for sending Enter
   enterExclude?: RegExp[]; // array of regex to exclude from auto-enter (even if enter matches)
   typingRespond?: { [message: string]: RegExp[] }; // type specified message to a specified pattern
+  autoRetry?: RegExp[]; // recoverable API errors (overload/rate-limit/usage-limit): type "retry" with exponential backoff (up to 8h) instead of exiting
 
   // crash/resuming-session behaviour
   restoreArgs?: string[]; // arguments to continue the session when crashed
@@ -341,6 +344,10 @@ export default async function agentYes({
     }
   }
 
+  // Opportunistic sweep: reap any process group leaked by an agent whose wrapper
+  // died without cleanup, before we start a new one. See ts/reaper.ts.
+  reaper.sweep().catch(() => {});
+
   // Spawn the agent CLI process
   const ptyEnv = { ...(env ?? (process.env as Record<string, string>)) };
   ptyEnv.AGENT_YES_PID = String(process.pid);
@@ -387,6 +394,10 @@ export default async function agentYes({
   } catch (error) {
     logger.warn(`[pidStore] Failed to register process ${shell.pid}:`, error);
   }
+  // Defense-in-depth: record (this wrapper, the agent's process group) so a later
+  // sweep reaps the group if we're killed without running onExit cleanup. The PTY
+  // child is a session leader, so its pgid == shell.pid. See ts/reaper.ts.
+  reaper.register(process.pid, shell.pid).catch(() => {});
   notifyWebhook("RUNNING", prompt ?? "", workingDir).catch(() => null);
 
   // Initialize log paths (independent of registration)
@@ -449,6 +460,19 @@ export default async function agentYes({
 
   shell.onExit(async function onExit({ exitCode }) {
     const exitedPid = shell.pid; // Capture PID immediately before any shell reassignment
+    // Reap the exited agent's process group. The PTY child is a session/group
+    // leader, so a `yes | cmd` (or any descendant) it leaked shares its pgid even
+    // after it reparents to PID 1 — kill the group so orphans don't spin at ~100%
+    // CPU forever. Targeting the pgid (not ppid==1) is container-safe and never
+    // touches processes outside this agent's session. Runs on the final exit AND
+    // before each robust restart below.
+    if (process.platform !== "win32") {
+      try {
+        process.kill(-exitedPid, "SIGKILL");
+      } catch {
+        // ESRCH = no surviving group members left to reap; nothing to do.
+      }
+    }
     // Unregister from agent registry
     globalAgentRegistry.unregister(exitedPid);
     ctx.stdinReady.unready(); // start buffer stdin
@@ -504,6 +528,10 @@ export default async function agentYes({
       } catch (error) {
         logger.warn(`[pidStore] Failed to register restarted process ${shell.pid}:`, error);
       }
+      // Re-register the NEW process group with the reaper — the restart gave us a
+      // fresh pgid; without this the reaper would track the old (now-dead) group
+      // and the live one would leak if we're SIGKILLed. Mirrors the Rust loop.
+      reaper.register(process.pid, shell.pid).catch(() => {});
       // Update context with new shell
       ctx.shell = shell;
       // Register new agent in registry (non-blocking)
@@ -612,6 +640,9 @@ export default async function agentYes({
       } catch (error) {
         logger.warn(`[pidStore] Failed to register restored process ${shell.pid}:`, error);
       }
+      // Re-register the NEW process group with the reaper (fresh pgid after the
+      // restore) so the reaper tracks the live group, not the dead one. See above.
+      reaper.register(process.pid, shell.pid).catch(() => {});
       // Update context with new shell
       ctx.shell = shell;
       // Register new agent in registry (non-blocking)
@@ -683,10 +714,52 @@ export default async function agentYes({
   // Heartbeat for auto-response on rendered terminal output
   // This catches patterns that appear via CSI positioning instead of newlines
   let lastHeartbeatRendered = "";
+  // Auto-retry backoff state (mirrors rs/src/context.rs). `streak` doubles the
+  // backoff each consecutive failed retry; `startedAt` anchors the 8h give-up
+  // window; `nextAt` is non-null while a retry is scheduled. `autoRetryScreen`
+  // is the latest rendered screen captured by the stdout pipeline below — the
+  // heartbeat timer reads it (its own xtermProxy.tail() is empty for EOL CLIs).
+  let retryStreak = 0;
+  let retryStartedAt: number | null = null;
+  let retryNextAt: number | null = null;
+  let autoRetryScreen = "";
   const heartbeatInterval = setInterval(async () => {
     try {
       const rendered = removeControlCharacters(xtermProxy.tail(12));
 
+      // Auto-retry backoff timer — fires the scheduled "retry" using the latest
+      // rendered screen captured by the stdout pipeline (consoleResponder). Runs
+      // every tick (independent of output) so it still fires while the agent sits
+      // idle on an error. Arming/reset lives in the stdout pipeline because this
+      // heartbeat's own xtermProxy.tail() is empty for newline (EOL) CLIs like
+      // claude. Only types "retry" when idle at a prompt (never mid-work).
+      if (retryNextAt !== null) {
+        const now = Date.now();
+        if (retryStartedAt !== null && now - retryStartedAt >= AUTO_RETRY_GIVE_UP_MS) {
+          logger.warn(`[${cli}-yes] auto-retry: giving up after 8h with no recovery`);
+          retryNextAt = null;
+          retryStartedAt = null;
+          retryStreak = 0;
+        } 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
+          } else {
+            retryStreak += 1;
+            logger.warn(`[${cli}-yes] auto-retry: typing 'retry' (attempt ${retryStreak})`);
+            // Write "retry" + 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.idleWaiter.ping();
+            // 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);
+          }
+        }
+      }
+
       // Skip if output hasn't changed since last heartbeat
       if (rendered === lastHeartbeatRendered) return;
       lastHeartbeatRendered = rendered;
@@ -1012,6 +1085,35 @@ export default async function agentYes({
 
             logger.debug(`stdout|${line}`);
 
+            // Auto-retry on recoverable API errors (overload / rate-limit / usage-
+            // limit): arm/reset the backoff on the whole rendered screen (the error
+            // banner and the ready prompt are on different lines, so this can't be a
+            // per-line check). The firing happens on the heartbeat timer, which
+            // reads `autoRetryScreen`. Done here, before the `fatal` check below, so
+            // these recoverable errors retry instead of exiting.
+            if (conf.autoRetry?.length) {
+              autoRetryScreen = rendered;
+              const errVisible = conf.autoRetry.some((rx: RegExp) => rx.test(rendered));
+              const readyVisible = conf.ready?.some((rx: RegExp) => rx.test(rendered)) ?? false;
+              if (errVisible && readyVisible) {
+                if (retryNextAt === null) {
+                  if (retryStartedAt === null) retryStartedAt = Date.now();
+                  const delayMs = autoRetryBackoffMs(retryStreak);
+                  retryNextAt = Date.now() + delayMs;
+                  logger.warn(
+                    `[${cli}-yes] auto-retry armed: recoverable error detected, retrying in ${
+                      delayMs / 1000
+                    }s (attempt ${retryStreak + 1})`,
+                  );
+                }
+              } else if (readyVisible && !errVisible && retryStartedAt !== null) {
+                logger.debug(`[${cli}-yes] auto-retry: recovered, resetting backoff`);
+                retryStreak = 0;
+                retryStartedAt = null;
+                retryNextAt = null;
+              }
+            }
+
             // ready matcher: if matched, mark stdin ready
             if (conf.ready?.some((rx: RegExp) => line.match(rx))) {
               logger.debug(`ready |${line}`);

package/ts/oxmgrService.ts

@@ -0,0 +1,36 @@
+// Register oxmgr's daemon with the platform init system (launchd on macOS,
+// systemd on Linux, Task Scheduler on Windows) so managed processes survive a
+// *reboot*, not just a crash.
+//
+// CHEAP + idempotent: it first checks `oxmgr service status` and SKIPS the
+// install when the service is already registered. This matters a lot —
+// re-running `oxmgr service install` re-bootstraps the launchd/systemd job,
+// which restarts the oxmgr daemon itself, and a daemon restart kills and
+// relaunches EVERY managed process (not just ours). Doing that on every
+// `ay serve install` / `ay schedule` was bouncing unrelated daemons — e.g. a
+// VS Code `serve-web` server running under another managed process, which took
+// the user's editor (and any agent running inside it) down with it.
+//
+// Best-effort: returns false on any failure (e.g. a system-level systemd unit
+// that needs sudo) without aborting the caller — the process is still managed,
+// just not boot-persistent.
+export async function ensureBootAutostart(oxmgrBin: string): Promise<boolean> {
+  try {
+    // Already registered with the init system? Then we're done — don't bounce
+    // the daemon (and all its children) just to re-assert what's already true.
+    const status = Bun.spawn([oxmgrBin, "service", "status"], {
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    if ((await status.exited) === 0) return true;
+
+    // Not registered yet → install. `--system` defaults to "auto"
+    // (launchd/systemd/Task Scheduler by platform); it's a `service`-level flag,
+    // so passing it after `install` is rejected.
+    const svc = Bun.spawn([oxmgrBin, "service", "install"], {
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return (await svc.exited) === 0;
+  } catch {
+    return false;
+  }
+}

package/ts/pty.ts

@@ -15,6 +15,24 @@ async function getPty(): Promise<typeof import("node-pty") | typeof import("bun-
       });
 }
 export type IPty = IPtyNode | IPtyBun;
-const pty = await getPty();
+type PtyModule = typeof import("node-pty") | typeof import("bun-pty");
+
+// Loading node-pty/bun-pty pulls in a native addon. Failing here at import time
+// would crash anything that merely imports this module's graph — including unit
+// tests that never spawn a PTY (e.g. on a machine where the prebuilt binary is
+// missing). So if the load fails, defer the error to first actual use: hand back
+// a proxy that re-throws the original load error the moment `pty.spawn` (or any
+// member) is touched. Production paths that do spawn still fail loudly, with the
+// same error and the same `logger.error` already emitted by getPty().
+let pty: PtyModule;
+try {
+  pty = await getPty();
+} catch (error) {
+  pty = new Proxy({} as PtyModule, {
+    get() {
+      throw error;
+    },
+  });
+}
 export const ptyPackage = globalThis.Bun ? "bun-pty" : "node-pty";
 export default pty;

package/ts/reaper.spec.ts

@@ -0,0 +1,45 @@
+import { afterEach, beforeEach, expect, test } from "vitest";
+import { mkdtempSync, readFileSync } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+import { register, sweep } from "./reaper.ts";
+
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  prevHome = process.env.AGENT_YES_HOME;
+  process.env.AGENT_YES_HOME = mkdtempSync(path.join(tmpdir(), "ay-reaper-"));
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.AGENT_YES_HOME;
+  else process.env.AGENT_YES_HOME = prevHome;
+});
+
+const registryFile = () => path.join(process.env.AGENT_YES_HOME!, "reaper.jsonl");
+const liveLines = () =>
+  readFileSync(registryFile(), "utf8")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+
+test("sweep keeps live wrappers and drops dead ones", async () => {
+  // A live wrapper (us) is kept; a dead wrapper (999999) is dropped. Neither
+  // pgid points at a real group, so the kill is a harmless ESRCH no-op — we only
+  // exercise the bookkeeping here, not real signalling.
+  await register(process.pid, 222_222);
+  await register(999_999, 999_998);
+  await sweep();
+
+  const lines = liveLines();
+  expect(lines.length).toBe(1);
+  expect(lines[0]).toContain(String(process.pid));
+});
+
+test("register refuses to persist a pgid <= 1", async () => {
+  await register(process.pid, 1);
+  await register(process.pid, 0);
+  // Nothing written, so the registry file doesn't exist — sweep is a no-op.
+  await sweep();
+  expect(() => readFileSync(registryFile(), "utf8")).toThrow();
+});

package/ts/reaper.ts

@@ -0,0 +1,77 @@
+// Defense-in-depth orphan reaper — mirrors rs/src/reaper.rs (see it for the full
+// rationale). Records each running agent's (wrapper pid, agent pgid) so a later
+// sweep kills the recorded process group of any agent whose wrapper died WITHOUT
+// running its own group cleanup (SIGKILL by an OOM killer / oxmgr force-restart /
+// a panic). It targets the recorded pgid of a CONFIRMED-DEAD wrapper — never
+// ppid==1 — so it is container-safe and never touches an unrelated process.
+
+import { appendFile, mkdir, readFile, rename, writeFile } from "fs/promises";
+import path from "path";
+import { agentYesHome } from "./agentYesHome.ts";
+
+const registryPath = () => path.join(agentYesHome(), "reaper.jsonl");
+
+function isAlive(pid: number): boolean {
+  if (pid <= 1) return false;
+  try {
+    process.kill(pid, 0); // signal 0 probes existence without affecting the target
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM"; // exists, owned by another user
+  }
+}
+
+/** Record this wrapper + its agent's process group for later sweeping. */
+export async function register(wrapperPid: number, pgid: number): Promise<void> {
+  if (pgid <= 1) return; // never persist a group we'd refuse to signal
+  try {
+    await mkdir(agentYesHome(), { recursive: true });
+    await appendFile(registryPath(), JSON.stringify({ wpid: wrapperPid, pgid }) + "\n");
+  } catch {
+    // best-effort
+  }
+}
+
+/** SIGKILL the recorded group of every agent whose wrapper has exited, and
+ *  rewrite the registry keeping only still-running agents. Best-effort. */
+export async function sweep(): Promise<void> {
+  let content: string;
+  try {
+    content = await readFile(registryPath(), "utf8");
+  } catch {
+    return; // no registry yet
+  }
+  const keep: string[] = [];
+  for (const line of content.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    let entry: { wpid?: unknown; pgid?: unknown };
+    try {
+      entry = JSON.parse(t);
+    } catch {
+      continue; // drop malformed lines
+    }
+    if (typeof entry.wpid !== "number" || typeof entry.pgid !== "number") continue;
+    if (isAlive(entry.wpid)) {
+      keep.push(t); // agent still running — keep watching it
+      continue;
+    }
+    // Wrapper gone — reap its recorded group. The pgid outlives the leader, so
+    // this catches descendants already reparented to PID 1. The `> 1` guard is
+    // critical: process.kill(-1) would signal every process the user owns.
+    if (process.platform !== "win32" && entry.pgid > 1) {
+      try {
+        process.kill(-entry.pgid, "SIGKILL");
+      } catch {
+        // ESRCH = nothing left alive in that group
+      }
+    }
+  }
+  try {
+    const tmp = registryPath() + ".tmp";
+    await writeFile(tmp, keep.join("\n"));
+    await rename(tmp, registryPath());
+  } catch {
+    // best-effort
+  }
+}

package/ts/schedule.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { shellQuote, toCron } from "./schedule.ts";
+
+describe("toCron", () => {
+  it("expands HH:MM to a daily cron", () => {
+    expect(toCron("10:00")).toBe("0 10 * * *");
+    expect(toCron("9:05")).toBe("5 9 * * *");
+    expect(toCron("23:59")).toBe("59 23 * * *");
+  });
+  it("passes through a 5-field cron expression", () => {
+    expect(toCron("0 10 * * *")).toBe("0 10 * * *");
+    expect(toCron("*/15 * * * 1-5")).toBe("*/15 * * * 1-5");
+  });
+  it("rejects out-of-range times and malformed specs", () => {
+    expect(toCron("25:00")).toBeNull();
+    expect(toCron("10:75")).toBeNull();
+    expect(toCron("daily")).toBeNull();
+    expect(toCron("0 10 * *")).toBeNull(); // only 4 fields
+    expect(toCron("")).toBeNull();
+  });
+});
+
+describe("shellQuote", () => {
+  it("wraps in single quotes for oxmgr's shell parsing", () => {
+    expect(shellQuote("a b c")).toBe("'a b c'");
+  });
+  it("escapes embedded single quotes", () => {
+    expect(shellQuote("it's a test")).toBe(`'it'\\''s a test'`);
+  });
+});