agent-yes 1.122.2 → 1.123.0

package/ts/globalPidIndex.ts

@@ -41,6 +41,12 @@ export interface GlobalPidRecord {
   // known until after spawn), so this maps that env value back to the agent's
   // canonical record — see resolveSender() in subcommands.ts.
   wrapper_pid?: number | null;
+  // The AGENT_YES_PID this wrapper *inherited* from its own environment when it
+  // started — i.e. the wrapper_pid of the PARENT agent that spawned this one (a
+  // nested `ay` launched from inside another agent). Null for top-level agents
+  // started from a human shell. Builds the agent>subagent tree: a child links to
+  // its parent via child.parent_pid === parent.wrapper_pid. See buildAgentForest.
+  parent_pid?: number | null;
 }
 
 /**
@@ -60,14 +66,13 @@ export function getGlobalPidIndexPath(): string {
   return resolveGlobalFile();
 }
 
-async function ensureDir() {
-  await mkdir(resolveGlobalDir(), { recursive: true });
-}
-
-async function withLock<R>(fn: () => Promise<R>): Promise<R> {
-  await ensureDir();
-  const file = resolveGlobalFile();
-  const dir = resolveGlobalDir();
+// Locks/operates on the `file` the CALLER resolved (at call time). Resolving the
+// path up front — before any await — keeps fire-and-forget writes from landing in
+// a different ~/.agent-yes if AGENT_YES_HOME changes before the async write runs
+// (notably tests that set+reset it around an un-awaited mirror write).
+async function withLock<R>(file: string, fn: () => Promise<R>): Promise<R> {
+  const dir = path.dirname(file);
+  await mkdir(dir, { recursive: true });
   let release: (() => Promise<void>) | undefined;
   try {
     release = await lock(dir, {
@@ -82,9 +87,10 @@ async function withLock<R>(fn: () => Promise<R>): Promise<R> {
 
 /** Append one full record line. Caller must provide all required fields. */
 export async function appendGlobalPid(record: GlobalPidRecord): Promise<void> {
+  const file = resolveGlobalFile(); // capture at call time (see withLock)
   try {
-    await withLock(async () => {
-      await appendFile(resolveGlobalFile(), JSON.stringify(record) + "\n");
+    await withLock(file, async () => {
+      await appendFile(file, JSON.stringify(record) + "\n");
     });
   } catch (error) {
     logger.debug("[globalPidIndex] append failed:", error);
@@ -96,13 +102,14 @@ export async function updateGlobalPidStatus(
   pid: number,
   patch: Partial<Pick<GlobalPidRecord, "status" | "exit_code" | "exit_reason" | "log_file">>,
 ): Promise<void> {
+  const file = resolveGlobalFile(); // capture at call time (see withLock)
   try {
-    await withLock(async () => {
-      const current = await readGlobalPidsRaw();
+    await withLock(file, async () => {
+      const current = await readGlobalPidsRaw(file);
       const existing = current.find((r) => r.pid === pid);
       if (!existing) return; // unknown pid — nothing to update
       const merged: GlobalPidRecord = { ...existing, ...patch };
-      await appendFile(resolveGlobalFile(), JSON.stringify(merged) + "\n");
+      await appendFile(file, JSON.stringify(merged) + "\n");
     });
   } catch (error) {
     logger.debug("[globalPidIndex] updateStatus failed:", error);
@@ -112,10 +119,10 @@ export async function updateGlobalPidStatus(
 /**
  * Read the file once without merge logic — internal helper for status updates.
  */
-async function readGlobalPidsRaw(): Promise<GlobalPidRecord[]> {
+async function readGlobalPidsRaw(file: string = resolveGlobalFile()): Promise<GlobalPidRecord[]> {
   let raw: string;
   try {
-    raw = await readFile(resolveGlobalFile(), "utf-8");
+    raw = await readFile(file, "utf-8");
   } catch (err: any) {
     if (err.code === "ENOENT") return [];
     throw err;
@@ -169,9 +176,10 @@ const COMPACT_THRESHOLD_LINES = 500; // raw events; one merged record per pid
  * it no-ops when the file is already small enough.
  */
 export async function maybeCompactGlobalPids(): Promise<void> {
+  const file = resolveGlobalFile(); // capture at call time (see withLock)
   let raw: string;
   try {
-    raw = await readFile(resolveGlobalFile(), "utf-8");
+    raw = await readFile(file, "utf-8");
   } catch (err: any) {
     if (err.code === "ENOENT") return;
     return;
@@ -180,15 +188,15 @@ export async function maybeCompactGlobalPids(): Promise<void> {
   if (lineCount < COMPACT_THRESHOLD_LINES) return;
 
   try {
-    await withLock(async () => {
-      const merged = await readGlobalPidsRaw();
+    await withLock(file, async () => {
+      const merged = await readGlobalPidsRaw(file);
       // Drop dead-and-exited entries; keep dead-but-not-yet-exited so a later
       // status-update from elsewhere can still be matched against them.
       const keep = merged.filter((r) => r.status !== "exited" || isProcessAlive(r.pid));
-      const tmpFile = resolveGlobalFile() + ".compact";
+      const tmpFile = file + ".compact";
       const content = keep.map((r) => JSON.stringify(r)).join("\n") + (keep.length ? "\n" : "");
       await writeFile(tmpFile, content);
-      await rename(tmpFile, resolveGlobalFile());
+      await rename(tmpFile, file);
       logger.debug(`[globalPidIndex] compacted ${lineCount} → ${keep.length} lines`);
     });
   } catch (error) {

package/ts/idleWaiter.spec.ts

@@ -3,8 +3,14 @@ import { IdleWaiter } from "./idleWaiter";
 
 describe("IdleWaiter", () => {
   it("should initialize with current time", () => {
+    // Bracket the constructor instead of a magic toBeCloseTo tolerance: the
+    // timestamp must fall within [before, after], which can't flake on a slow CI
+    // runner (a GC pause would just widen the bracket, never break it).
+    const before = Date.now();
     const waiter = new IdleWaiter();
-    expect(waiter.lastActivityTime).toBeCloseTo(Date.now(), -2);
+    const after = Date.now();
+    expect(waiter.lastActivityTime).toBeGreaterThanOrEqual(before);
+    expect(waiter.lastActivityTime).toBeLessThanOrEqual(after);
   });
 
   it("should update lastActivityTime when ping is called", () => {

package/ts/index.ts

@@ -65,6 +65,7 @@ export type AgentCliConfig = {
   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
+  needsInput?: RegExp[]; // agent is blocked on an interactive selection menu it did NOT auto-resolve; surfaced as the `needs_input` state by `ay ls`/`ay status` (query-time only — not consumed by the run loop)
 
   // crash/resuming-session behaviour
   restoreArgs?: string[]; // arguments to continue the session when crashed
@@ -350,6 +351,12 @@ export default async function agentYes({
 
   // Spawn the agent CLI process
   const ptyEnv = { ...(env ?? (process.env as Record<string, string>)) };
+  // Capture the AGENT_YES_PID we INHERITED (the wrapper of the parent agent that
+  // launched this nested `ay`) before we overwrite it with our own pid below.
+  // null when started from a human shell → this agent is a tree root.
+  const inheritedAyPid = Number(ptyEnv.AGENT_YES_PID);
+  const parentPid =
+    Number.isInteger(inheritedAyPid) && inheritedAyPid > 0 ? inheritedAyPid : undefined;
   ptyEnv.AGENT_YES_PID = String(process.pid);
   const ptyOptions = {
     name: "xterm-color",
@@ -390,6 +397,8 @@ export default async function agentYes({
       // We inject our own pid as AGENT_YES_PID into the agent's env above; record
       // it so a child `ay send` can map that env value back to this agent.
       wrapperPid: process.pid,
+      // The parent agent's wrapper pid (inherited AGENT_YES_PID), for the tree.
+      parentPid,
     });
   } catch (error) {
     logger.warn(`[pidStore] Failed to register process ${shell.pid}:`, error);

package/ts/lsWatch.spec.ts

@@ -0,0 +1,61 @@
+import { expect, test } from "vitest";
+import { diffLsStates, type LsAgentState } from "./lsWatch.ts";
+
+const agent = (
+  pid: number,
+  state: LsAgentState["state"],
+  question: string | null = null,
+): LsAgentState => ({
+  pid,
+  cli: "claude",
+  cwd: "/repo",
+  state,
+  question,
+});
+
+test("first observation of each agent is a baseline event (prev_state null)", () => {
+  const { events, next } = diffLsStates(new Map(), [agent(1, "active"), agent(2, "idle")], 100);
+  expect(events).toHaveLength(2);
+  expect(events.every((e) => e.prev_state === null)).toBe(true);
+  expect(next.size).toBe(2);
+});
+
+test("no event when nothing changed", () => {
+  const prev = new Map([[1, agent(1, "active")]]);
+  const { events } = diffLsStates(prev, [agent(1, "active")], 200);
+  expect(events).toHaveLength(0);
+});
+
+test("emits a transition when state changes (active -> needs_input)", () => {
+  const prev = new Map([[1, agent(1, "active")]]);
+  const { events } = diffLsStates(prev, [agent(1, "needs_input", "Pick auth?")], 300);
+  expect(events).toHaveLength(1);
+  expect(events[0]).toMatchObject({
+    pid: 1,
+    state: "needs_input",
+    question: "Pick auth?",
+    prev_state: "active",
+  });
+});
+
+test("re-emits when the question text changes within needs_input", () => {
+  const prev = new Map([[1, agent(1, "needs_input", "Q1")]]);
+  const { events } = diffLsStates(prev, [agent(1, "needs_input", "Q2")], 400);
+  expect(events).toHaveLength(1);
+  expect(events[0]!.question).toBe("Q2");
+});
+
+test("synthesizes a stopped event when an agent is reaped between ticks", () => {
+  const prev = new Map([[1, agent(1, "active")]]);
+  const { events, next } = diffLsStates(prev, [], 500);
+  expect(events).toHaveLength(1);
+  expect(events[0]).toMatchObject({ pid: 1, state: "stopped", prev_state: "active" });
+  expect(next.size).toBe(0);
+});
+
+test("does not double-emit stopped for an agent already seen stopped then gone", () => {
+  // Already known as stopped, then it drops out of the set → no synthetic event.
+  const prev = new Map([[1, agent(1, "stopped")]]);
+  const { events } = diffLsStates(prev, [], 600);
+  expect(events).toHaveLength(0);
+});

package/ts/lsWatch.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure transition-diffing core for `ay ls --watch` — a single NDJSON event
+ * stream of agent state changes across ALL (filtered) agents, so a fan-out
+ * orchestrator watches one process instead of spawning N per-pid
+ * `ay status <pid> --watch`es.
+ *
+ * The polling/timer lives in `cmdLs`; this module is the pure, synchronous diff
+ * between "what I knew last tick" and "what I see now", so it is trivially
+ * unit-testable. Keeping it runtime-agnostic and side-effect-free mirrors
+ * `needsInput.ts`.
+ */
+
+export type LiveState = "active" | "idle" | "stopped" | "needs_input";
+
+/** The observable state of one agent at a single tick. */
+export interface LsAgentState {
+  pid: number;
+  cli: string;
+  cwd: string;
+  state: LiveState;
+  /** Pending menu text when state === "needs_input", else null. */
+  question: string | null;
+}
+
+/** One emitted transition (NDJSON line under `ay ls --watch`). */
+export interface LsWatchEvent {
+  ts: number;
+  pid: number;
+  cli: string;
+  cwd: string;
+  state: LiveState;
+  question: string | null;
+  /**
+   * The state this agent was last seen in, or null when this is the first time
+   * we observe the agent (the baseline emit). Lets a consumer distinguish a
+   * genuine transition from the initial snapshot.
+   */
+  prev_state: LiveState | null;
+}
+
+/**
+ * Diff the previous per-pid states against the current snapshot and return the
+ * transition events to emit plus the next prev-map. Pure: no I/O, no clock —
+ * the caller passes `ts`.
+ *
+ * Emits an event when:
+ *  - an agent is seen for the first time (baseline, `prev_state: null`)
+ *  - its `state` or `question` changed since last tick
+ *  - it vanished from the live set without us ever seeing it `stopped` (reaped
+ *    between ticks) — a synthetic `stopped` event so a "done" transition is
+ *    never silently dropped.
+ */
+export function diffLsStates(
+  prev: Map<number, LsAgentState>,
+  cur: LsAgentState[],
+  ts: number,
+): { events: LsWatchEvent[]; next: Map<number, LsAgentState> } {
+  const events: LsWatchEvent[] = [];
+  const next = new Map<number, LsAgentState>();
+  const curPids = new Set<number>();
+
+  for (const a of cur) {
+    curPids.add(a.pid);
+    next.set(a.pid, a);
+    const p = prev.get(a.pid);
+    if (!p) {
+      events.push({ ...toEvent(a, ts), prev_state: null });
+    } else if (p.state !== a.state || p.question !== a.question) {
+      events.push({ ...toEvent(a, ts), prev_state: p.state });
+    }
+  }
+
+  // Agents that dropped out of the live set (reaped) before we observed their
+  // exit: synthesize a stopped transition so consumers see the agent finish.
+  for (const [pid, p] of prev) {
+    if (!curPids.has(pid) && p.state !== "stopped") {
+      events.push({
+        ts,
+        pid,
+        cli: p.cli,
+        cwd: p.cwd,
+        state: "stopped",
+        question: null,
+        prev_state: p.state,
+      });
+    }
+  }
+
+  return { events, next };
+}
+
+function toEvent(a: LsAgentState, ts: number): Omit<LsWatchEvent, "prev_state"> {
+  return { ts, pid: a.pid, cli: a.cli, cwd: a.cwd, state: a.state, question: a.question };
+}

package/ts/needsInput.spec.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "vitest";
+import { classifyNeedsInput } from "./needsInput.ts";
+import { loadSharedCliDefaults } from "./configShared.ts";
+
+// Use the REAL shipped claude/codex patterns so the test guards the actual config.
+const defaults = await loadSharedCliDefaults();
+const claude = { needsInput: defaults.claude?.needsInput, working: defaults.claude?.working };
+const codex = { needsInput: defaults.codex?.needsInput, working: defaults.codex?.working };
+
+test("claude config actually ships a needsInput pattern", () => {
+  expect(claude.needsInput?.length).toBeGreaterThan(0);
+});
+
+test("detects a claude AskUserQuestion selection menu", () => {
+  const screen = [
+    "Which auth method should we use?",
+    "",
+    "❯ 1. Session tokens",
+    "  2. JWT",
+    "  3. OAuth",
+    "",
+    "? for shortcuts",
+  ];
+  const ni = classifyNeedsInput(screen, claude);
+  expect(ni).not.toBeNull();
+  expect(ni!.question).toContain("auth method");
+});
+
+test("a plain idle prompt is NOT needs_input", () => {
+  const screen = ['❯ Try "fix the bug in auth.ts"', "", "? for shortcuts"];
+  expect(classifyNeedsInput(screen, claude)).toBeNull();
+});
+
+test("an actively-working agent is NOT needs_input even if a menu lingers above", () => {
+  const screen = [
+    "❯ 1. Session tokens", // stale menu in scrollback
+    "✻ Working… (3s · esc to interrupt)",
+  ];
+  expect(classifyNeedsInput(screen, claude)).toBeNull();
+});
+
+test("regular numbered output (no cursor glyph) is NOT a menu", () => {
+  const screen = ["Here are the steps:", "1. do this", "2. then that", "? for shortcuts"];
+  expect(classifyNeedsInput(screen, claude)).toBeNull();
+});
+
+test("detects a codex selection menu (› cursor)", () => {
+  const screen = ["Pick a branch to target", "› 1. main", "  2. develop"];
+  const ni = classifyNeedsInput(screen, codex);
+  expect(ni).not.toBeNull();
+});
+
+test("no patterns configured → always null", () => {
+  expect(classifyNeedsInput(["❯ 1. anything"], { needsInput: [], working: [] })).toBeNull();
+});

package/ts/needsInput.ts

@@ -0,0 +1,68 @@
+/**
+ * Detect, from an agent's rendered TUI screen, whether it is blocked on an
+ * interactive selection menu it did NOT auto-resolve — i.e. it `needs_input`.
+ *
+ * This is a QUERY-time classifier (used by `ay ls` / `ay status`), deliberately
+ * not part of the run loop: the same drawn menu is observable regardless of which
+ * runtime (Rust or TS) produced it, so detection is runtime-agnostic and needs no
+ * new IPC or persisted state. The signal is the menu cursor sitting on a numbered
+ * option (config `needsInput` patterns, e.g. claude `❯ N.`, codex `›/> N.`). An
+ * agent that is actively `working` is never `needs_input`, even if an old menu
+ * lingers in the scrollback.
+ */
+
+export interface NeedsInput {
+  /** A compact rendering of the pending question/menu, for `ay status --json`. */
+  question: string;
+}
+
+// Config regexes are authored without the global/sticky flags, but strip them
+// defensively so `.test()` can't carry `lastIndex` state across calls.
+function reTest(re: RegExp, s: string): boolean {
+  return (re.global || re.sticky ? new RegExp(re.source, re.flags.replace(/[gy]/g, "")) : re).test(
+    s,
+  );
+}
+
+function isChromeLine(s: string): boolean {
+  const t = s.trim();
+  return (
+    !t ||
+    /^─+$/.test(t) ||
+    /^esc to (interrupt|cancel)/i.test(t) ||
+    /\? for shortcuts/.test(t) ||
+    /\d+%\s*until auto-compact/i.test(t)
+  );
+}
+
+/**
+ * Returns a NeedsInput when the screen shows an unresolved selection menu, else
+ * null. `cfg.working` short-circuits to null (an actively-working agent isn't
+ * blocked). Pure + synchronous so it's trivially unit-testable.
+ */
+export function classifyNeedsInput(
+  lines: string[],
+  cfg: { needsInput?: RegExp[]; working?: RegExp[] },
+): NeedsInput | null {
+  const patterns = cfg.needsInput ?? [];
+  if (patterns.length === 0) return null;
+
+  const text = lines.join("\n");
+  // `working` wins: a spinner means real work is happening, not a blocking prompt.
+  if ((cfg.working ?? []).some((re) => reTest(re, text))) return null;
+  if (!patterns.some((re) => reTest(re, text))) return null;
+
+  // Build a compact question from the menu region: the last line carrying the
+  // menu cursor, plus a little context above (the question) and the options below.
+  let last = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (patterns.some((re) => reTest(re, lines[i]!))) last = i;
+  }
+  const start = Math.max(0, last - 6);
+  const end = Math.min(lines.length, last + 6);
+  const block = lines
+    .slice(start, end)
+    .map((l) => l.trim())
+    .filter((l) => l && !isChromeLine(l));
+  return { question: block.join(" • ").slice(0, 400) };
+}

package/ts/pidStore.ts

@@ -55,6 +55,7 @@ export class PidStore {
     prompt,
     cwd,
     wrapperPid,
+    parentPid,
   }: {
     pid: number;
     cli: string;
@@ -62,6 +63,7 @@ export class PidStore {
     prompt?: string;
     cwd: string;
     wrapperPid?: number;
+    parentPid?: number;
   }): Promise<PidRecord> {
     const now = Date.now();
     const argsJson = JSON.stringify(args);
@@ -116,6 +118,7 @@ export class PidStore {
       exit_reason: null,
       started_at: now,
       wrapper_pid: wrapperPid ?? null,
+      parent_pid: parentPid ?? null,
     })
       .then(() => maybeCompactGlobalPids())
       .catch(() => null);

package/ts/reaper.spec.ts

@@ -1,8 +1,8 @@
 import { afterEach, beforeEach, expect, test } from "vitest";
-import { mkdtempSync, readFileSync } from "fs";
+import { mkdtempSync, readFileSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import path from "path";
-import { register, sweep } from "./reaper.ts";
+import { pgidForWrapper, register, sweep } from "./reaper.ts";
 
 let prevHome: string | undefined;
 
@@ -43,3 +43,27 @@ test("register refuses to persist a pgid <= 1", async () => {
   await sweep();
   expect(() => readFileSync(registryFile(), "utf8")).toThrow();
 });
+
+test("pgidForWrapper returns the newest matching pgid, ignoring junk + bad entries", async () => {
+  writeFileSync(
+    registryFile(),
+    [
+      JSON.stringify({ wpid: 4242, pgid: 100 }),
+      "not-json", // malformed → skipped, not thrown
+      "", // blank → skipped
+      JSON.stringify({ wpid: 9999, pgid: 200 }), // different wrapper → ignored for 4242
+      JSON.stringify({ wpid: 4242, pgid: 1 }), // pgid <= 1 → ignored
+      JSON.stringify({ wpid: 4242, pgid: 300 }), // newest valid for 4242 → wins
+    ].join("\n") + "\n",
+  );
+  expect(await pgidForWrapper(4242)).toBe(300);
+  expect(await pgidForWrapper(9999)).toBe(200);
+  expect(await pgidForWrapper(1234)).toBeNull(); // no entry for this wrapper
+});
+
+test("pgidForWrapper returns null for an invalid wpid or a missing registry", async () => {
+  expect(await pgidForWrapper(0)).toBeNull(); // !wpid
+  expect(await pgidForWrapper(1)).toBeNull(); // wpid <= 1 (never ppid==1)
+  // Fresh home, no registry file written → readFile throws → null (not a crash).
+  expect(await pgidForWrapper(4242)).toBeNull();
+});

package/ts/reaper.ts

@@ -21,6 +21,31 @@ function isAlive(pid: number): boolean {
   }
 }
 
+/** The recorded process-group id for a wrapper pid (newest entry wins), or null
+ *  if unknown. Lets a force-kill target the agent's whole group, not just its
+ *  wrapper pid — same registry the orphan sweep uses. */
+export async function pgidForWrapper(wpid: number): Promise<number | null> {
+  if (!wpid || wpid <= 1) return null;
+  let content: string;
+  try {
+    content = await readFile(registryPath(), "utf8");
+  } catch {
+    return null;
+  }
+  let pgid: number | null = null;
+  for (const line of content.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const e = JSON.parse(t);
+      if (e.wpid === wpid && typeof e.pgid === "number" && e.pgid > 1) pgid = e.pgid;
+    } catch {
+      // skip malformed
+    }
+  }
+  return pgid;
+}
+
 /** 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

package/ts/resultEnvelope.spec.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { buildStoredResult, normalizeEnvelope, resultPath, resultsDir } from "./resultEnvelope.ts";
+
+describe("normalizeEnvelope", () => {
+  it("passes a JSON object through unchanged", () => {
+    const out = normalizeEnvelope('{"status":"done","commits":["abc123"]}');
+    expect(out).toEqual({ status: "done", commits: ["abc123"] });
+  });
+
+  it("keeps JSON arrays and scalars as-is (agent owns the shape)", () => {
+    expect(normalizeEnvelope("[1,2,3]")).toEqual([1, 2, 3]);
+    expect(normalizeEnvelope("42")).toBe(42);
+  });
+
+  it("wraps non-JSON text as a summary instead of rejecting", () => {
+    expect(normalizeEnvelope("shipped the fix")).toEqual({ summary: "shipped the fix" });
+  });
+
+  it("trims surrounding whitespace before parsing", () => {
+    expect(normalizeEnvelope('  \n {"ok":true}\n ')).toEqual({ ok: true });
+  });
+
+  it("returns null for empty / whitespace-only input", () => {
+    expect(normalizeEnvelope("")).toBeNull();
+    expect(normalizeEnvelope("   \n\t")).toBeNull();
+  });
+});
+
+describe("buildStoredResult", () => {
+  it("wraps the payload with correlation metadata", () => {
+    expect(buildStoredResult(123, { status: "done" }, 1000)).toEqual({
+      pid: 123,
+      written_at: 1000,
+      result: { status: "done" },
+    });
+  });
+});
+
+describe("resultPath", () => {
+  it("derives a per-pid path under the results dir", () => {
+    expect(resultPath(777)).toBe(`${resultsDir()}/777.json`);
+  });
+});

package/ts/resultEnvelope.ts

@@ -0,0 +1,88 @@
+/**
+ * Structured result envelope — P4 of the orchestrator-observability work.
+ *
+ * A fan-out parent that spawned a sub-agent wants its *outcome* (branch, commit
+ * SHAs, changed files, status, blockers, a summary) as machine-readable data,
+ * not by grepping `ay tail`. This is the agent-yes analog of an in-harness
+ * Agent tool's `<result>` block. The sub-agent deposits one JSON envelope when
+ * it finishes; the parent pulls it with `ay result <keyword>`.
+ *
+ * Why a PERSISTED file, not a query-time screen scrape (the model that
+ * `needs_input`/activity use): a completion record is read AFTER the agent is
+ * done — exactly when its rendered screen is gone and its log may be reaped. It
+ * must outlive the process, so it is written once to
+ * `$AGENT_YES_HOME/results/<pid>.json` and read back verbatim. It is keyed by
+ * the wrapper pid the agent already knows via the injected `AGENT_YES_PID` env
+ * var, so depositing needs no new spawn-time wiring in either runtime.
+ *
+ * This module is the pure, fs-free core (path math + input normalization) so it
+ * is trivially unit-testable, mirroring `lsWatch.ts` / `needsInput.ts`. The fs
+ * read/write + CLI live in `subcommands.ts` (`cmdResult`).
+ */
+
+import path from "path";
+import { agentYesHome } from "./agentYesHome.ts";
+
+/**
+ * The on-disk shape: agent payload (`result`) plus the minimal metadata a
+ * consumer needs to correlate it. `result` is whatever JSON the agent emitted —
+ * we don't enforce a schema, only suggest one (see `ResultPayload`).
+ */
+export interface StoredResult {
+  pid: number;
+  written_at: number;
+  result: unknown;
+}
+
+/**
+ * The SUGGESTED envelope an agent emits. None of it is required or validated —
+ * it documents the convention an orchestrator can rely on when it controls the
+ * sub-agent's prompt. Extra fields pass through untouched.
+ */
+export interface ResultPayload {
+  /** Operator-facing rollup: "done", "blocked", "failed", or free text. */
+  status?: string;
+  /** One-line (or short) summary of what was accomplished. */
+  summary?: string;
+  /** Git branch the work landed on. */
+  branch?: string;
+  /** Commit SHAs produced, oldest→newest. */
+  commits?: string[];
+  /** Paths touched (relative to the repo root). */
+  files?: string[];
+  /** Anything that blocked completion / needs the parent's attention. */
+  blockers?: string[];
+  [k: string]: unknown;
+}
+
+/** Directory holding the per-pid result files. */
+export function resultsDir(): string {
+  return path.join(agentYesHome(), "results");
+}
+
+/** Absolute path of one agent's result envelope. */
+export function resultPath(pid: number): string {
+  return path.join(resultsDir(), `${pid}.json`);
+}
+
+/**
+ * Coerce raw write-side input into an envelope payload. If it parses as JSON we
+ * keep it as-is (object, array, or scalar — the agent owns the shape). If it
+ * does NOT parse, we don't reject: a bare string is a perfectly good summary, so
+ * we wrap it as `{ summary }`. Empty / whitespace-only input is an error the
+ * caller should surface (returns null).
+ */
+export function normalizeEnvelope(raw: string): unknown | null {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return { summary: trimmed } satisfies ResultPayload;
+  }
+}
+
+/** Wrap a normalized payload with correlation metadata for persistence. */
+export function buildStoredResult(pid: number, result: unknown, writtenAt: number): StoredResult {
+  return { pid, written_at: writtenAt, result };
+}