agent-yes 1.287.0 → 1.288.0

package/ts/cwdConflictWarn.bun.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "bun:test";
+import { formatCwdConflictWarning, shQuote } from "./cwdConflictWarn.ts";
+
+describe("cwdConflictWarn.formatCwdConflictWarning", () => {
+  const cwd = "/code/proj/tree/main";
+
+  it("returns null when no peers occupy the cwd", () => {
+    expect(formatCwdConflictWarning([], cwd, "ay claude")).toBeNull();
+  });
+
+  it("warns and suggests a git-worktree command for a single peer", () => {
+    const msg = formatCwdConflictWarning([{ pid: 111, cli: "claude" }], cwd, "ay claude -- fix");
+    expect(msg).toContain("1 agent is already running in this directory (/code/proj/tree/main)");
+    expect(msg).toContain("111  claude");
+    // uses `git worktree add` (not `git clone .`) — worktree name = dir + branch
+    expect(msg).toContain("git worktree add -b main-work ../main-work && cd ../main-work");
+    expect(msg).not.toContain("git clone");
+    // original command is appended so the suggestion is copy-pasteable
+    expect(msg).toContain("&& ay claude -- fix");
+    expect(msg).toContain("AGENT_YES_NO_CWD_WARN=1");
+  });
+
+  it("pluralizes and lists at most 3 peers with an overflow count", () => {
+    const peers = [1, 2, 3, 4, 5].map((n) => ({ pid: n, cli: "codex" }));
+    const msg = formatCwdConflictWarning(peers, cwd, "ay codex")!;
+    expect(msg).toContain("5 agents are already running");
+    expect(msg).toContain("1  codex");
+    expect(msg).toContain("3  codex");
+    expect(msg).not.toContain("4  codex"); // capped at 3 listed
+    expect(msg).toContain("…and 2 more");
+  });
+
+  it("falls back to a placeholder when cwd has no basename or command is empty", () => {
+    const msg = formatCwdConflictWarning([{ pid: 9, cli: "codex" }], "/", "   ")!;
+    expect(msg).toContain("../agent-work"); // basename('/') is empty → 'agent'
+    expect(msg).toContain("&& ay <cli> …"); // empty origCmd → placeholder
+  });
+});
+
+describe("cwdConflictWarn.shQuote", () => {
+  it("passes safe tokens through unquoted", () => {
+    expect(shQuote("ay")).toBe("ay");
+    expect(shQuote("claude")).toBe("claude");
+    expect(shQuote("--")).toBe("--");
+    expect(shQuote("../main-work")).toBe("../main-work");
+    expect(shQuote("main-work_2.3")).toBe("main-work_2.3");
+  });
+
+  it("single-quotes tokens with spaces or shell metacharacters", () => {
+    expect(shQuote("fix the bug")).toBe("'fix the bug'");
+    expect(shQuote("a;rm -rf b")).toBe("'a;rm -rf b'");
+    expect(shQuote("$HOME")).toBe("'$HOME'");
+    expect(shQuote("")).toBe("''");
+  });
+
+  it("escapes embedded single quotes safely", () => {
+    // POSIX close-quote / escaped-quote / reopen-quote dance
+    expect(shQuote("it's")).toBe(`'it'\\''s'`);
+  });
+});

package/ts/cwdPassthroughHint.bun.spec.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "bun:test";
+import { detectCwdPassthrough } from "./cwdPassthroughHint.ts";
+
+// argv shape is [exec, script, ...userArgs]; the script's basename is the
+// program name the user typed (cy/ay/claude-yes/…).
+const argv = (script: string, ...user: string[]) => ["/usr/bin/bun", script, ...user];
+
+describe("detectCwdPassthrough", () => {
+  it("returns null when --cwd is absent", () => {
+    expect(detectCwdPassthrough(argv("/x/dist/cy.js", "claude", "-p", "hi"))).toBeNull();
+  });
+
+  it("detects `--cwd DIR` and rebuilds the command without it", () => {
+    const dep = detectCwdPassthrough(
+      argv("/x/dist/cy.js", "claude", "--cwd", "/ws/app", "-p", "fix"),
+    );
+    expect(dep).not.toBeNull();
+    expect(dep!.dir).toBe("/ws/app");
+    expect(dep!.suggestion).toBe("cd /ws/app && cy claude -p fix");
+  });
+
+  it("detects `--cwd=DIR` form", () => {
+    const dep = detectCwdPassthrough(argv("/x/dist/agent-yes.js", "codex", "--cwd=/tmp/x"));
+    expect(dep!.dir).toBe("/tmp/x");
+    expect(dep!.suggestion).toBe("cd /tmp/x && agent-yes codex");
+  });
+
+  it("keeps a home-relative dir bare so the shell still expands ~", () => {
+    const dep = detectCwdPassthrough(argv("/x/dist/cy.js", "--cwd", "~/ws/product"));
+    expect(dep!.suggestion).toBe("cd ~/ws/product && cy");
+  });
+
+  it("preserves the prompt after `--` and quotes tokens with spaces", () => {
+    // The shell splits `-- solve all todos` into one argv token per word.
+    const dep = detectCwdPassthrough(
+      argv("/x/dist/claude-yes.js", "--cwd", "/ws/app", "--", "solve", "all", "todos"),
+    );
+    // A single already-quoted token keeping its space is re-quoted for display.
+    const dep2 = detectCwdPassthrough(
+      argv("/x/dist/claude-yes.js", "--cwd", "/ws/app", "--", "a b"),
+    );
+    expect(dep!.suggestion).toBe("cd /ws/app && claude-yes -- solve all todos");
+    expect(dep2!.suggestion).toBe("cd /ws/app && claude-yes -- 'a b'");
+  });
+
+  it("quotes a dir containing spaces", () => {
+    const dep = detectCwdPassthrough(argv("/x/dist/cy.js", "--cwd", "/my ws/app"));
+    expect(dep!.suggestion).toBe("cd '/my ws/app' && cy");
+  });
+
+  it("handles `--cwd` given as the last token with no value", () => {
+    const dep = detectCwdPassthrough(argv("/x/dist/cy.js", "claude", "--cwd"));
+    expect(dep).not.toBeNull();
+    expect(dep!.dir).toBeUndefined();
+    expect(dep!.suggestion).toBe("cd <dir> && cy claude");
+  });
+
+  it("says the flag is passed through, not handled", () => {
+    const dep = detectCwdPassthrough(argv("/x/dist/cy.js", "--cwd", "/ws"));
+    expect(dep!.message).toContain("--cwd is not an agent-yes flag");
+    expect(dep!.message).toContain("cd /ws && cy");
+  });
+
+  it("ignores a --cwd that appears after `--`", () => {
+    // Past the separator the token belongs to the CLI or the prompt. It is
+    // forwarded verbatim either way, so there is nothing to suggest.
+    expect(
+      detectCwdPassthrough(argv("/x/dist/cy.js", "claude", "--", "--cwd", "/ws/app")),
+    ).toBeNull();
+    expect(
+      detectCwdPassthrough(argv("/x/dist/cy.js", "claude", "--", "run with --cwd=/ws")),
+    ).toBeNull();
+  });
+});

package/ts/e2e-crypto.bun.spec.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect } from "bun:test";
+import {
+  V,
+  PROTO,
+  MARKER,
+  FLAG_CONFIRM,
+  validateS,
+  deriveAuthToken,
+  deriveDirKeys,
+  computeTranscriptHash,
+  seal,
+  open,
+  packEnvelope,
+  unpackEnvelope,
+  parseSecret,
+  randomHex,
+} from "../lab/ui/e2e.js";
+
+const S = "a".repeat(64); // a valid 64-hex secret for tests
+const S2 = "b".repeat(64);
+const TH = new Uint8Array(32).fill(7); // a fake transcript hash
+const TH2 = new Uint8Array(32).fill(9);
+
+// Minimal but realistic SDP fragments carrying the lines the binding reads.
+function sdp(fp: string, setup: string, ufrag: string): string {
+  return [
+    "v=0",
+    "o=- 1 1 IN IP4 0.0.0.0",
+    "s=-",
+    "t=0 0",
+    "m=application 9 UDP/DTLS/SCTP webrtc-datachannel",
+    `a=ice-ufrag:${ufrag}`,
+    `a=setup:${setup}`,
+    `a=fingerprint:${fp}`,
+  ].join("\r\n");
+}
+const FP_A = "sha-256 AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99";
+const FP_B = "sha-256 11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00";
+
+describe("e2e version constants", () => {
+  it("are internally consistent", () => {
+    expect(V).toBe(1);
+    expect(PROTO).toBe("ay-e2e-1");
+    expect(MARKER).toBe("e1.");
+    expect(FLAG_CONFIRM).toBe(0x01);
+  });
+});
+
+describe("validateS", () => {
+  it("accepts a 64-hex secret", () => {
+    expect(validateS(S)).toBe(S);
+  });
+  it("rejects bad input without echoing it", () => {
+    for (const bad of ["", "xyz", S.toUpperCase(), "e1." + S, S + "0", 123 as unknown as string]) {
+      try {
+        validateS(bad);
+        throw new Error("should have thrown for " + bad);
+      } catch (e) {
+        expect((e as Error).message).toBe("invalid share token");
+        expect((e as Error).message).not.toContain(String(bad).slice(0, 8) || "∅");
+      }
+    }
+  });
+});
+
+describe("deriveAuthToken", () => {
+  it("is deterministic and 64-hex", async () => {
+    const a = await deriveAuthToken(S, "room1", "s.agent-yes.com");
+    const b = await deriveAuthToken(S, "room1", "s.agent-yes.com");
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{64}$/);
+  });
+  it("is not equal to S (one-way) and binds room + sighost", async () => {
+    const base = await deriveAuthToken(S, "room1", "s.agent-yes.com");
+    expect(base).not.toBe(S);
+    expect(await deriveAuthToken(S, "room2", "s.agent-yes.com")).not.toBe(base);
+    expect(await deriveAuthToken(S, "room1", "other.host")).not.toBe(base);
+    expect(await deriveAuthToken(S2, "room1", "s.agent-yes.com")).not.toBe(base);
+  });
+});
+
+describe("seal / open round trip", () => {
+  it("round-trips a sealed envelope", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const send = { sendCtr: 0n };
+    const recv = { lastSeen: -1n };
+    const frame = await seal(keyH2C, send, 0, TH, packEnvelope({ t: "req", id: "x", path: "/p" }));
+    expect(frame).toBeInstanceOf(ArrayBuffer);
+    expect(new Uint8Array(frame)[0]).toBe(0x01); // VER
+    const { plaintext, counter, flags } = await open(keyH2C, frame, TH, recv);
+    expect(counter).toBe(0n);
+    expect(flags).toBe(0);
+    expect(unpackEnvelope(plaintext)).toEqual({ t: "req", id: "x", path: "/p" });
+  });
+
+  it("increments the counter and never repeats a nonce, even concurrently", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const send = { sendCtr: 0n };
+    const [f0, f1] = await Promise.all([
+      seal(keyH2C, send, 0, TH, packEnvelope({ n: 0 })),
+      seal(keyH2C, send, 0, TH, packEnvelope({ n: 1 })),
+    ]);
+    const nonce = (f: ArrayBuffer) => new Uint8Array(f).slice(2, 14).join(",");
+    expect(nonce(f0)).not.toBe(nonce(f1));
+    expect(send.sendCtr).toBe(2n);
+  });
+
+  it("carries the confirmation FLAG through", async () => {
+    const { keyC2H } = await deriveDirKeys(S, TH);
+    const frame = await seal(
+      keyC2H,
+      { sendCtr: 0n },
+      FLAG_CONFIRM,
+      TH,
+      packEnvelope({ t: "confirm" }),
+    );
+    const { flags } = await open(keyC2H, frame, TH, { lastSeen: -1n });
+    expect(flags & FLAG_CONFIRM).toBe(FLAG_CONFIRM);
+  });
+});
+
+describe("open is fail-closed", () => {
+  it("rejects a tampered ciphertext bit", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    const bytes = new Uint8Array(frame);
+    const last = bytes.length - 1;
+    bytes[last] = (bytes[last] ?? 0) ^ 0x01; // flip a tag bit
+    await expect(open(keyH2C, bytes, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a tampered header (VER/FLAGS/NONCE are authenticated)", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    const bytes = new Uint8Array(frame);
+    bytes[1] = (bytes[1] ?? 0) ^ 0x02; // flip a FLAGS bit
+    await expect(open(keyH2C, bytes, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a bad version byte", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    const bytes = new Uint8Array(frame);
+    bytes[0] = 0x02;
+    await expect(open(keyH2C, bytes, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a frame bound to a different transcript (per-frame binding)", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    await expect(open(keyH2C, frame, TH2, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects the wrong direction key", async () => {
+    const { keyH2C, keyC2H } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    await expect(open(keyC2H, frame, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a first frame whose counter is not 0", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 5n }, 0, TH, packEnvelope({ t: "confirm" }));
+    await expect(open(keyH2C, frame, TH, { lastSeen: -1n })).rejects.toThrow(/counter-0/);
+  });
+  it("rejects a frame from a different session (per-session keys)", async () => {
+    const a = await deriveDirKeys(S, TH);
+    const b = await deriveDirKeys(S, TH2);
+    const frame = await seal(a.keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    // different key AND different AAD → fails
+    await expect(open(b.keyH2C, frame, TH2, { lastSeen: -1n })).rejects.toThrow();
+  });
+});
+
+describe("anti-replay (mandatory)", () => {
+  it("rejects a replayed frame and an out-of-order frame", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const send = { sendCtr: 0n };
+    const recv = { lastSeen: -1n };
+    const f0 = await seal(keyH2C, send, 0, TH, packEnvelope({ n: 0 }));
+    const f1 = await seal(keyH2C, send, 0, TH, packEnvelope({ n: 1 }));
+    await open(keyH2C, f0, TH, recv); // counter 0 ok
+    await open(keyH2C, f1, TH, recv); // counter 1 ok
+    await expect(open(keyH2C, f1, TH, recv)).rejects.toThrow(/replay/); // replay counter 1
+    await expect(open(keyH2C, f0, TH, recv)).rejects.toThrow(/replay/); // reorder back to 0
+  });
+});
+
+describe("computeTranscriptHash", () => {
+  it("matches across ends with offer/answer swapped", async () => {
+    const local = sdp(FP_A, "actpass", "ufragLOCAL");
+    const remote = sdp(FP_B, "active", "ufragREMOTE");
+    // host: offer=local, answer=remote ; client: offer=remote(as seen), answer=local
+    const host = await computeTranscriptHash(local, remote);
+    const client = await computeTranscriptHash(local, remote);
+    expect(Buffer.from(host).toString("hex")).toBe(Buffer.from(client).toString("hex"));
+    // a different fingerprint changes the hash
+    const other = await computeTranscriptHash(
+      sdp(FP_A, "actpass", "ufragLOCAL"),
+      sdp(FP_A, "active", "x"),
+    );
+    expect(Buffer.from(other).toString("hex")).not.toBe(Buffer.from(host).toString("hex"));
+  });
+  it("fails closed on a missing fingerprint", async () => {
+    const noFp = "v=0\r\na=setup:active\r\na=ice-ufrag:u";
+    await expect(computeTranscriptHash(sdp(FP_A, "actpass", "u"), noFp)).rejects.toThrow(
+      /fingerprint/,
+    );
+  });
+  it("fails closed on a non-sha-256 fingerprint (downgrade)", async () => {
+    const sha1 = sdp("sha-1 AA:BB:CC", "active", "u");
+    await expect(computeTranscriptHash(sdp(FP_A, "actpass", "u"), sha1)).rejects.toThrow(/sha-256/);
+  });
+});
+
+describe("parseSecret marker grammar (strict, fail-closed)", () => {
+  it("parses v2 encrypted links", () => {
+    expect(parseSecret("e1." + S)).toEqual({ s: S, v2: true });
+  });
+  it("treats a bare 64-hex token and a pid as legacy (caller gates)", () => {
+    expect(parseSecret(S)).toEqual({ s: S, v2: false });
+    expect(parseSecret("12345")).toEqual({ s: "12345", v2: false });
+  });
+  it("rejects an unknown version marker (update required)", () => {
+    expect(() => parseSecret("e2." + S)).toThrow(/update required/);
+    expect(() => parseSecret("e10." + S)).toThrow(/update required/);
+  });
+  it("rejects marker-shaped-but-malformed tokens (never legacy)", () => {
+    expect(() => parseSecret("e1." + "z".repeat(64))).toThrow(/malformed/);
+    expect(() => parseSecret("e1." + "a".repeat(63))).toThrow(/malformed/);
+    expect(() => parseSecret("e1" + S)).toThrow(/malformed/); // marker-like, no dot
+    expect(() => parseSecret("E1." + S)).toThrow(/malformed/); // wrong case is not v2
+  });
+});
+
+describe("randomHex", () => {
+  it("returns n bytes of hex and varies", () => {
+    expect(randomHex(16)).toMatch(/^[0-9a-f]{32}$/);
+    expect(randomHex(16)).not.toBe(randomHex(16));
+  });
+});

package/ts/forkNested.bun.spec.ts

@@ -0,0 +1,240 @@
+import { appendFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  buildSpawnTutorial,
+  confirmAgentStarted,
+  predictedLogPath,
+  shouldForkNested,
+  waitForRegistration,
+} 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("waitForRegistration", () => {
+  let home: string;
+  let prevHome: string | undefined;
+
+  const appendPid = (record: Record<string, unknown>) =>
+    appendFileSync(path.join(home, "pids.jsonl"), JSON.stringify(record) + "\n");
+
+  beforeEach(() => {
+    home = mkdtempSync(path.join(tmpdir(), "ay-forknested-"));
+    prevHome = process.env.AGENT_YES_HOME;
+    process.env.AGENT_YES_HOME = home;
+  });
+
+  afterEach(() => {
+    if (prevHome === undefined) delete process.env.AGENT_YES_HOME;
+    else process.env.AGENT_YES_HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  it("resolves true once the pid registry has a live record for this pid", async () => {
+    // Register the pid a poll-tick after the wait starts, like a real spawn.
+    setTimeout(
+      () =>
+        appendPid({
+          pid: 111,
+          cli: "claude",
+          prompt: null,
+          cwd: "/tmp",
+          log_file: null,
+          status: "active",
+          exit_code: null,
+          exit_reason: null,
+          started_at: Date.now(),
+        }),
+      60,
+    );
+    await expect(waitForRegistration(111, 2000)).resolves.toBe(true);
+  });
+
+  it("times out false when the agent never registers", async () => {
+    await expect(waitForRegistration(222, 120)).resolves.toBe(false);
+  });
+
+  it("does NOT count a record whose status is already exited", async () => {
+    appendPid({
+      pid: 333,
+      cli: "claude",
+      prompt: null,
+      cwd: "/tmp",
+      log_file: null,
+      status: "exited",
+      exit_code: 1,
+      exit_reason: "crash",
+      started_at: Date.now(),
+    });
+    await expect(waitForRegistration(333, 120)).resolves.toBe(false);
+  });
+
+  it("fails fast when aborted() reports the child already died", async () => {
+    const start = Date.now();
+    await expect(waitForRegistration(444, 5000, () => true)).resolves.toBe(false);
+    expect(Date.now() - start).toBeLessThan(1000); // no full-timeout wait
+  });
+});
+
+describe("confirmAgentStarted", () => {
+  let home: string;
+  let proj: string;
+  let prevHome: string | undefined;
+
+  const appendPid = (record: Record<string, unknown>) =>
+    appendFileSync(path.join(home, "pids.jsonl"), JSON.stringify(record) + "\n");
+
+  const live = (pid: number, over: Record<string, unknown> = {}) => ({
+    pid,
+    cli: "claude",
+    prompt: null,
+    cwd: proj,
+    log_file: null,
+    status: "active",
+    exit_code: null,
+    exit_reason: null,
+    started_at: Date.now(),
+    ...over,
+  });
+
+  /** Write the raw log the wrapper produces once the CLI is really up. */
+  const writeRawLog = (pid: number, body = "\x1b[?25l hello") => {
+    mkdirSync(path.join(proj, ".agent-yes"), { recursive: true });
+    writeFileSync(predictedLogPath(proj, pid), body);
+  };
+
+  beforeEach(() => {
+    home = mkdtempSync(path.join(tmpdir(), "ay-confirm-home-"));
+    proj = mkdtempSync(path.join(tmpdir(), "ay-confirm-proj-"));
+    prevHome = process.env.AGENT_YES_HOME;
+    process.env.AGENT_YES_HOME = home;
+  });
+
+  afterEach(() => {
+    if (prevHome === undefined) delete process.env.AGENT_YES_HOME;
+    else process.env.AGENT_YES_HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+    rmSync(proj, { recursive: true, force: true });
+  });
+
+  it("fails when the agent flips to exited inside the grace window — the #387 race", async () => {
+    appendPid(live(501));
+    setTimeout(
+      () => appendPid(live(501, { status: "exited", exit_code: 1, exit_reason: "fatal" })),
+      60,
+    );
+    const res = await confirmAgentStarted(501, 2000);
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.reason).toContain("exited during startup");
+      expect(res.reason).toContain("fatal");
+      expect(res.reason).toContain("ay tail 501");
+    }
+  });
+
+  it("puts the agent's own error output in the failure message", async () => {
+    const errLog = path.join(proj, "boom.log");
+    writeFileSync(errLog, "error: unknown option '--cwd'\n");
+    appendPid(
+      live(502, { status: "exited", exit_code: 1, exit_reason: "fatal", log_file: errLog }),
+    );
+    const res = await confirmAgentStarted(502, 300);
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.reason).toContain("error: unknown option '--cwd'");
+  });
+
+  it("reports death even when the agent produced output before dying", async () => {
+    writeRawLog(503);
+    appendPid(live(503, { status: "exited", exit_code: 1, exit_reason: "fatal" }));
+    // Liveness must never outrank the failure check within a tick.
+    await expect(confirmAgentStarted(503, 300)).resolves.toMatchObject({ ok: false });
+  });
+
+  it("returns early once the raw log proves the CLI is up", async () => {
+    appendPid(live(504));
+    writeRawLog(504);
+    const start = Date.now();
+    await expect(confirmAgentStarted(504, 5000)).resolves.toEqual({ ok: true });
+    expect(Date.now() - start).toBeLessThan(1000); // did not pay the whole grace
+  });
+
+  it("succeeds at the deadline when the agent is alive but quiet", async () => {
+    appendPid(live(505));
+    await expect(confirmAgentStarted(505, 250)).resolves.toEqual({ ok: true });
+  });
+
+  it("fails when aborted() reports the wrapper already died", async () => {
+    appendPid(live(506));
+    const res = await confirmAgentStarted(506, 5000, () => true);
+    expect(res.ok).toBe(false);
+  });
+
+  it("fails when the record vanished — compaction drops dead+exited agents", async () => {
+    const res = await confirmAgentStarted(507, 300);
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.reason).toContain("disappeared from the registry");
+  });
+});
+
+describe("predictedLogPath", () => {
+  it("matches the Rust wrapper's <cwd>/.agent-yes/<pid>.raw.log convention", () => {
+    expect(predictedLogPath("/home/u/proj", 4242)).toBe(
+      path.join("/home/u/proj", ".agent-yes", "4242.raw.log"),
+    );
+  });
+});
+
+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");
+    expect(out).toContain("ay notify watch --unread");
+    expect(out).toContain("Monitor (preferred");
+  });
+});
+
+describe("buildSpawnTutorial — the parent's half of the contract", () => {
+  it("offers the monitor route first, for a harness that has one", () => {
+    const out = buildSpawnTutorial("claude", 4242);
+    expect(out).toContain("ay ls --watch --json");
+    expect(out).toContain("ay status 4242");
+    expect(out).toContain("--wait-idle");
+  });
+
+  it("tells the parent the push is a fallback that yields to a watcher", () => {
+    const out = buildSpawnTutorial("claude", 4242);
+    expect(out).toContain("<ay-report");
+    expect(out).toMatch(/finishes, gets stuck, or exits/);
+    expect(out).toContain("stays quiet while you are actively watching");
+  });
+
+  it("still lists the drive commands (a parent may want to intervene early)", () => {
+    const out = buildSpawnTutorial("codex", 7);
+    expect(out).toContain("ay tail 7");
+    expect(out).toContain(`ay send 7 "..."`);
+  });
+});