agent-yes 1.265.4 → 1.266.0

package/ts/initMsg.ts

@@ -0,0 +1,107 @@
+/**
+ * `<ay-init-msg …>` — the attribution wrapper around a SUB-AGENT's INITIAL prompt.
+ *
+ * `ay send` already wraps every agent→agent message in `<ay-msg nonce from …>`
+ * so the recipient knows who pinged it and exactly how to reply (see cmdSend in
+ * ts/subcommands.ts). The initial prompt had no such wrapper: an agent spawned by
+ * `ay claude -- "<task>"` from inside another agent's Bash tool received a bare
+ * task string with no idea that (a) it was spawned by an agent rather than a
+ * human, (b) that agent is blocked/waiting on it, or (c) how to talk back. It
+ * would finish, sit at an idle prompt, and nobody would ever learn.
+ *
+ * So the first message gets the same treatment as every later one — same
+ * nonce-delimited XML-ish framing, same `reply:` route — plus the one thing a
+ * later message doesn't need: an explicit REPORTING DUTY (ping the parent when
+ * you finish, and when you're stuck). The runtime enforces that duty
+ * independently in ts/parentPing.ts; this block is what makes the agent do it
+ * deliberately, with content, instead of the wrapper's terse automatic ping.
+ *
+ * Pure + fs-free (the caller supplies the nonce) so it is trivially unit-testable,
+ * mirroring `notifyRouter.ts` / `resultEnvelope.ts`. Mirrored in the Rust runtime
+ * by `rs/src/init_msg.rs` — keep the two formats byte-identical.
+ */
+
+import { homedir } from "os";
+
+/** The agent that spawned this one, as far as the wrapper could resolve it. */
+export interface InitSpawner {
+  cli: string;
+  /** The spawner's agent pid (display only — pids die on restart). */
+  pid: number;
+  /**
+   * The spawner's stable agent_id, the ACTUAL reply route: it survives the
+   * parent restarting (a pid does not). Falls back to the pid when a legacy
+   * record carries no id.
+   */
+  agentId?: string | null;
+  cwd: string;
+}
+
+/** Replace a leading $HOME with `~`. Local copy of subcommands' shortenPath so
+ *  this module stays import-light (it runs on the wrapper's cold-start path). */
+export function shortenHome(p: string, home = homedir()): string {
+  if (!home || !p.startsWith(home)) return p;
+  const rest = p.slice(home.length);
+  if (rest !== "" && rest !== "/" && rest !== "\\") return "~" + rest;
+  return "~";
+}
+
+/** The stable id to address a reply to — agent_id when we have one, else pid. */
+export function replyTargetOf(spawner: InitSpawner): string {
+  const id = spawner.agentId?.trim();
+  return id ? id : String(spawner.pid);
+}
+
+/**
+ * Wrap a sub-agent's initial `prompt` in `<ay-init-msg …>`.
+ *
+ * `nonce` is generated by the CALLER, after the prompt text already exists, so
+ * text inside the body can't forge a matching open/close marker — the same
+ * forgery guard `<ay-msg>` relies on (nonce match, not tag syntax, is what makes
+ * the boundary trustworthy; strict-XML validity is deliberately sacrificed).
+ *
+ * Returns the prompt unchanged when there is no spawner (a top-level agent
+ * started from a human shell has nobody to report to, and the block would be
+ * pure noise on the overwhelmingly common path).
+ */
+export function buildInitMsg(
+  prompt: string,
+  spawner: InitSpawner | null | undefined,
+  nonce: string,
+): string {
+  if (!spawner) return prompt;
+  const target = replyTargetOf(spawner);
+  const where = shortenHome(spawner.cwd);
+  return [
+    `<ay-init-msg ${nonce} from ${spawner.cli} #${spawner.pid} @ ${where} — reply: ay send ${target} "...">`,
+    `<ay-task ${nonce}>`,
+    prompt,
+    `</ay-task ${nonce}>`,
+    ``,
+    `The task above was given to you by that agent — it spawned you and returned`,
+    `immediately, so it is NOT watching your terminal and will not see anything you`,
+    `print. Reach it by RUNNING THESE SHELL COMMANDS (in your bash/terminal tool):`,
+    `  ay send ${target} "..."          report progress, ask a question, deliver the result`,
+    `  ay tail ${target}                read what it has been doing`,
+    ``,
+    // Observed in the wild: a subagent under Claude Code read this block, reached
+    // for its harness's OWN agent-messaging tool ("SendMessage"/"ListAgents"),
+    // got "No agent named '<id>' is reachable" — that tool only knows the
+    // harness's own subagents, not agent-yes's registry — and gave up, reporting
+    // nothing. Naming the collision explicitly is what stops it: the agent must
+    // know these are shell commands and that its built-in tool cannot see us.
+    `\`ay\` is a SHELL COMMAND — run it in your bash/terminal tool. It is NOT your`,
+    `harness's built-in agent/message tool: that tool only knows agents your harness`,
+    `spawned and will say "no agent named ${target}". Do not substitute it, and do`,
+    `not conclude the parent is unreachable if it fails — use the shell.`,
+    ``,
+    `Reporting duty — you MUST run \`ay send ${target} "..."\` when either happens:`,
+    `  1. You finish the task. Send the outcome itself (what changed, what you found,`,
+    `     files/PRs touched), not just "done" — it cannot read your transcript.`,
+    `  2. You are blocked or stuck: a decision only it can make, a missing`,
+    `     credential/permission, a failing step you cannot get past. Say what you`,
+    `     tried and what you need. Do NOT sit at an idle prompt waiting.`,
+    `Until you do one of those, it is waiting on you.`,
+    `</ay-init-msg ${nonce}>`,
+  ].join("\n");
+}

package/ts/ownerHeartbeat.ts

@@ -138,6 +138,12 @@ export function startInlineHeartbeat(opts: OwnerHeartbeatOptions): OwnerHeartbea
   };
 }
 
+/** Upper bound on how long stop() waits for the worker thread to go away. Far
+ *  longer than a terminate needs; short enough that shutdown never looks wedged.
+ *  Overshooting only leaks an already-unref'd thread that cannot hold the
+ *  process open. */
+const STOP_TIMEOUT_MS = 2_000;
+
 export function startOwnerHeartbeat(opts: OwnerHeartbeatOptions): OwnerHeartbeat {
   try {
     const worker = new Worker(WORKER_SRC, {
@@ -154,10 +160,43 @@ export function startOwnerHeartbeat(opts: OwnerHeartbeatOptions): OwnerHeartbeat
     // relying on the main loop's own token check.
     worker.on("error", () => {});
     if (typeof worker.unref === "function") worker.unref();
+
+    // The worker EXITS ON ITS OWN whenever fencing fails: losing the token
+    // clears its interval, which drains its event loop. That is the normal,
+    // expected end for a superseded beat — so by the time anyone calls stop(),
+    // the thread is very often already gone, and `terminate()` on an
+    // already-exited worker does not reliably settle (it hangs under bun).
+    // Track the exit and race it, with a bounded fallback, so stop() ALWAYS
+    // resolves: it is awaited on the daemon's shutdown path, where hanging would
+    // wedge the process instead of merely leaking a thread.
+    let exited = false;
+    const exitedPromise = new Promise<void>((resolve) => {
+      worker.once("exit", () => {
+        exited = true;
+        resolve();
+      });
+    });
     return {
       isolated: true,
       stop: async () => {
-        await worker.terminate().catch(() => {});
+        if (exited) return;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const timeout = new Promise<void>((resolve) => {
+          timer = setTimeout(resolve, STOP_TIMEOUT_MS);
+          if (typeof timer.unref === "function") timer.unref();
+        });
+        try {
+          await Promise.race([
+            worker.terminate().then(
+              () => {},
+              () => {},
+            ),
+            exitedPromise,
+            timeout,
+          ]);
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
       },
     };
   } catch {

package/ts/parentLink.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { resolveSpawner, spawnerFromRecords } from "./parentLink.ts";
+import type { GlobalPidRecord } from "./globalPidIndex.ts";
+
+const rec = (over: Partial<GlobalPidRecord> = {}): GlobalPidRecord => ({
+  pid: 100,
+  cli: "claude",
+  prompt: null,
+  cwd: "/repo",
+  log_file: null,
+  status: "active",
+  exit_code: null,
+  exit_reason: null,
+  started_at: 1,
+  wrapper_pid: 99,
+  agent_id: "agt_a",
+  ...over,
+});
+
+describe("spawnerFromRecords", () => {
+  it("matches on wrapper_pid — that is the value a child inherits as AGENT_YES_PID", () => {
+    expect(spawnerFromRecords([rec()], 99)).toEqual({
+      cli: "claude",
+      pid: 100,
+      agentId: "agt_a",
+      cwd: "/repo",
+    });
+  });
+
+  it("returns null when nothing matches (parent aged out, or lives on another host)", () => {
+    expect(spawnerFromRecords([rec()], 12345)).toBeNull();
+    expect(spawnerFromRecords([], 99)).toBeNull();
+  });
+
+  it("prefers a LIVE record over a recycled wrapper pid's exited one", () => {
+    const dead = rec({ pid: 100, status: "exited", agent_id: "agt_old" });
+    const live = rec({ pid: 200, status: "active", agent_id: "agt_new" });
+    expect(spawnerFromRecords([dead, live], 99)?.agentId).toBe("agt_new");
+  });
+
+  it("falls back to an exited record rather than losing the link entirely", () => {
+    const dead = rec({ status: "exited", agent_id: "agt_old" });
+    expect(spawnerFromRecords([dead], 99)?.agentId).toBe("agt_old");
+  });
+
+  it("normalises a missing agent_id to null so the caller falls back to the pid", () => {
+    expect(spawnerFromRecords([rec({ agent_id: undefined })], 99)?.agentId).toBeNull();
+  });
+});
+
+describe("resolveSpawner", () => {
+  it("short-circuits on a non-parent without touching the registry", async () => {
+    await expect(resolveSpawner(undefined)).resolves.toBeNull();
+    await expect(resolveSpawner(null)).resolves.toBeNull();
+    await expect(resolveSpawner(0)).resolves.toBeNull();
+    await expect(resolveSpawner(-1)).resolves.toBeNull();
+    await expect(resolveSpawner(1.5)).resolves.toBeNull();
+  });
+
+  it("returns null (never throws) when the registry has no such parent", async () => {
+    // A pid that cannot be a live wrapper in this test process's registry.
+    await expect(resolveSpawner(2 ** 30)).resolves.toBeNull();
+  });
+});

package/ts/parentLink.ts

@@ -0,0 +1,58 @@
+/**
+ * Resolve "who spawned me" from the wrapper-pid link the registry already
+ * carries, into an addressable identity.
+ *
+ * The link itself is just a number: a nested `ay` inherits its parent wrapper's
+ * `AGENT_YES_PID` and records it as `parent_pid` (see globalPidIndex's
+ * GlobalPidRecord). To actually TALK to that parent — which is what
+ * `<ay-init-msg>` and the finished/stuck ping both need — we have to map that
+ * wrapper pid back to the parent's canonical record, because the reply route is
+ * its `agent_id` (stable across restart), not its pid.
+ *
+ * Shared by ts/initMsg.ts's caller and ts/parentPing's delivery so both address
+ * the SAME identity — a child that reports to a different route than the one
+ * printed in its own init block would be maddening to debug.
+ */
+
+import { readGlobalPids, type GlobalPidRecord } from "./globalPidIndex.ts";
+import type { InitSpawner } from "./initMsg.ts";
+
+/**
+ * The parent agent for `parentPid` (a parent WRAPPER pid), or null.
+ *
+ * Null covers three different situations that all mean the same thing here —
+ * "nobody to report to": no parent at all (top-level, human-launched); a parent
+ * whose record aged out of the registry; or a parent on another host. Callers
+ * treat all three as "skip the wrapper / skip the ping" rather than guessing a
+ * route that would silently go nowhere.
+ */
+export async function resolveSpawner(
+  parentPid: number | null | undefined,
+): Promise<InitSpawner | null> {
+  if (typeof parentPid !== "number" || !Number.isInteger(parentPid) || parentPid <= 0) return null;
+  let records: GlobalPidRecord[];
+  try {
+    records = await readGlobalPids();
+  } catch {
+    return null; // registry unreadable — never block a spawn over attribution
+  }
+  return spawnerFromRecords(records, parentPid);
+}
+
+/** Pure half of resolveSpawner, so the match rule is testable without the fs. */
+export function spawnerFromRecords(
+  records: GlobalPidRecord[],
+  parentPid: number,
+): InitSpawner | null {
+  // Prefer a live record: a recycled wrapper pid can match an old exited entry
+  // too, and reporting into a dead agent's fifo is worse than not reporting.
+  const matches = records.filter((r) => r.wrapper_pid === parentPid);
+  const parent = matches.find((r) => r.status !== "exited") ?? matches[0];
+  if (!parent) return null;
+  return {
+    cli: parent.cli,
+    pid: parent.pid,
+    agentId: parent.agent_id ?? null,
+    cwd: parent.cwd,
+  };
+}

package/ts/parentPing.spec.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_PING_CONFIG,
+  initialPingState,
+  repeatDelayMs,
+  stepParentPing,
+  type PingConfig,
+  type PingObservation,
+  type PingState,
+} from "./parentPing.ts";
+
+const CFG: PingConfig = {
+  idleConfirmMs: 30_000,
+  repeatBaseMs: 100_000,
+  repeatMaxMs: 400_000,
+  maxRepeats: 2,
+};
+
+/** Drive a sequence of observations, collecting every ping decided. */
+function run(obs: PingObservation[], cfg = CFG) {
+  let state: PingState = initialPingState();
+  const pings = [];
+  for (const o of obs) {
+    const r = stepParentPing(state, o, cfg);
+    state = r.state;
+    if (r.ping) pings.push(r.ping);
+  }
+  return { state, pings };
+}
+
+describe("repeatDelayMs", () => {
+  it("doubles per attempt and caps", () => {
+    expect(repeatDelayMs(1, CFG)).toBe(100_000);
+    expect(repeatDelayMs(2, CFG)).toBe(200_000);
+    expect(repeatDelayMs(3, CFG)).toBe(400_000);
+    expect(repeatDelayMs(4, CFG)).toBe(400_000); // capped
+  });
+});
+
+describe("finished (settled idle)", () => {
+  it("does not fire before idleConfirmMs — a breath between tool calls is not 'done'", () => {
+    const { pings } = run([
+      { now: 0, state: "idle" },
+      { now: 10_000, state: "idle" },
+      { now: 29_999, state: "idle" },
+    ]);
+    expect(pings).toEqual([]);
+  });
+
+  it("fires once the idle run clears idleConfirmMs", () => {
+    const { pings } = run([
+      { now: 0, state: "idle" },
+      { now: 30_000, state: "idle" },
+      { now: 35_000, state: "idle" },
+    ]);
+    expect(pings).toEqual([{ reason: "finished", attempt: 1, question: null }]);
+  });
+
+  it("resets the idle timer when the agent picks work back up", () => {
+    const { pings } = run([
+      { now: 0, state: "idle" },
+      { now: 20_000, state: "active" },
+      { now: 25_000, state: "idle" },
+      { now: 50_000, state: "idle" }, // only 25s into the NEW idle run
+    ]);
+    expect(pings).toEqual([]);
+  });
+
+  it("re-arms after activity, so a second round of work reports again", () => {
+    const { pings } = run([
+      { now: 0, state: "idle" },
+      { now: 40_000, state: "idle" }, // finished #1
+      { now: 50_000, state: "active" },
+      { now: 60_000, state: "idle" },
+      { now: 100_000, state: "idle" }, // finished #2
+    ]);
+    expect(pings.map((p) => [p.reason, p.attempt])).toEqual([
+      ["finished", 1],
+      ["finished", 1],
+    ]);
+  });
+});
+
+describe("stuck (needs_input)", () => {
+  it("fires immediately — a blocked agent has no hysteresis to earn", () => {
+    const { pings } = run([{ now: 0, state: "needs_input", question: "Approve edit?" }]);
+    expect(pings).toEqual([{ reason: "stuck", attempt: 1, question: "Approve edit?" }]);
+  });
+
+  it("does not re-fire on the same unchanged question", () => {
+    const { pings } = run([
+      { now: 0, state: "needs_input", question: "Approve edit?" },
+      { now: 1_000, state: "needs_input", question: "Approve edit?" },
+      { now: 2_000, state: "needs_input", question: "Approve edit?" },
+    ]);
+    expect(pings).toHaveLength(1);
+  });
+
+  it("re-fires on a CHANGED question — that is new information, not a repeat", () => {
+    const { pings } = run([
+      { now: 0, state: "needs_input", question: "Approve edit?" },
+      { now: 1_000, state: "needs_input", question: "Run tests?" },
+    ]);
+    expect(pings.map((p) => p.question)).toEqual(["Approve edit?", "Run tests?"]);
+    expect(pings.every((p) => p.attempt === 1)).toBe(true);
+  });
+
+  it("a stuck episode that decays to plain idle stays 'stuck', never 'finished'", () => {
+    const { pings } = run([
+      { now: 0, state: "needs_input", question: "Approve edit?" },
+      { now: 1_000, state: "idle" },
+      { now: 200_000, state: "idle" },
+    ]);
+    expect(pings.map((p) => p.reason)).toEqual(["stuck", "stuck"]);
+  });
+});
+
+describe("keep pinging until something changes", () => {
+  it("repeats an unanswered episode on the backoff, up to maxRepeats", () => {
+    const { pings } = run([
+      { now: 0, state: "needs_input", question: "q" }, // attempt 1
+      { now: 99_000, state: "needs_input", question: "q" }, // not due
+      { now: 100_000, state: "needs_input", question: "q" }, // attempt 2
+      { now: 300_000, state: "needs_input", question: "q" }, // attempt 3
+      { now: 900_000, state: "needs_input", question: "q" }, // maxRepeats exhausted
+      { now: 999_999, state: "needs_input", question: "q" },
+    ]);
+    expect(pings.map((p) => p.attempt)).toEqual([1, 2, 3]);
+  });
+
+  it("stops nagging once the agent goes active again", () => {
+    const { pings } = run([
+      { now: 0, state: "needs_input", question: "q" },
+      { now: 100_000, state: "active" },
+      { now: 500_000, state: "active" },
+    ]);
+    expect(pings).toHaveLength(1);
+  });
+});
+
+describe("exited", () => {
+  it("fires once and is terminal — nothing follows it", () => {
+    const { pings } = run([
+      { now: 0, state: "active" },
+      { now: 1_000, state: "exited" },
+      { now: 2_000, state: "exited" },
+      { now: 3_000, state: "idle" },
+      { now: 400_000, state: "idle" },
+    ]);
+    expect(pings).toEqual([{ reason: "exited", attempt: 1, question: null }]);
+  });
+
+  it("supersedes an open stuck episode", () => {
+    const { pings } = run([
+      { now: 0, state: "needs_input", question: "q" },
+      { now: 1_000, state: "exited" },
+    ]);
+    expect(pings.map((p) => p.reason)).toEqual(["stuck", "exited"]);
+  });
+});
+
+describe("defaults", () => {
+  it("ships a 30s idle confirm, matching notifyRouter", () => {
+    expect(DEFAULT_PING_CONFIG.idleConfirmMs).toBe(30_000);
+  });
+
+  it("uses the shipped defaults when no config is passed", () => {
+    let s = initialPingState();
+    let r = stepParentPing(s, { now: 0, state: "idle" });
+    expect(r.ping).toBeNull();
+    r = stepParentPing(r.state, { now: 29_000, state: "idle" });
+    expect(r.ping).toBeNull();
+    r = stepParentPing(r.state, { now: 31_000, state: "idle" });
+    expect(r.ping?.reason).toBe("finished");
+  });
+});

package/ts/parentPing.ts

@@ -0,0 +1,195 @@
+/**
+ * The sub-agent's own duty to PING ITS PARENT — pure edge/backoff state machine.
+ *
+ * `ay notifyd` already detects idle/needs_input/exited edges and files them into
+ * the parent's inbox, but that is a PULL channel: nothing is delivered unless the
+ * parent is running `ay notify watch`. The whole failure mode we care about is a
+ * parent that spawned a fan-out and then went back to its own work — i.e. exactly
+ * the parent that is NOT watching. `<ay-init-msg>` tells the child to report back,
+ * but an LLM that runs out of steam mid-task, crashes, or simply forgets will not.
+ *
+ * So the CHILD'S WRAPPER pushes, unconditionally: when the agent it supervises
+ * finishes (settled idle), gets stuck (parked on a question / wedged), or exits,
+ * it injects a message straight into the parent's stdin via `ay send`. That is
+ * the same channel a peer agent uses, so it lands in the parent's context whether
+ * or not the parent ever asked for it.
+ *
+ * "Keep pinging": a single ping can be missed — the parent may be mid-tool-call,
+ * or may have been compacted since. So an unresolved episode RE-pings on an
+ * escalating backoff up to `maxRepeats`, and the whole episode resets the moment
+ * the child goes active again (it got an answer, or picked the work back up).
+ *
+ * Pure + synchronous (the caller passes `now`) so it is unit-testable without a
+ * PTY or a clock, mirroring `notifyRouter.ts`. The delivery side lives in
+ * `parentPingSend.ts`; the wiring lives in `ts/index.ts`.
+ */
+
+/** What the child looks like right now, as classified by its own wrapper. */
+export type SelfState = "active" | "idle" | "needs_input" | "exited";
+
+/** Why we are pinging — becomes the report's headline. */
+export type PingReason = "finished" | "stuck" | "exited";
+
+export interface PingObservation {
+  now: number;
+  state: SelfState;
+  /** Compact question text when state === "needs_input", else null. */
+  question?: string | null;
+}
+
+export interface PingConfig {
+  /** How long the child must sit continuously idle before we call it "finished". */
+  idleConfirmMs: number;
+  /** Delay before the FIRST repeat of an unacknowledged episode. */
+  repeatBaseMs: number;
+  /** Cap for the doubling backoff between repeats. */
+  repeatMaxMs: number;
+  /** How many times to re-ping one episode before giving up (0 = ping once). */
+  maxRepeats: number;
+}
+
+export const DEFAULT_PING_CONFIG: PingConfig = {
+  // Matches notifyRouter's DEFAULT_IDLE_CONFIRM_MS: long enough that a pause
+  // between tool calls never reads as "done", short enough to be useful.
+  idleConfirmMs: 30_000,
+  repeatBaseMs: 120_000, // 2m → 4m → 8m → 15m (capped)
+  repeatMaxMs: 900_000,
+  maxRepeats: 4,
+};
+
+export interface PingState {
+  /** Last observed state, so we can detect the transition INTO an episode. */
+  state: SelfState | null;
+  /** When the current idle run began, or null when not idle. */
+  idleSince: number | null;
+  /** The reason of the episode we are currently pinging about, or null. */
+  episode: PingReason | null;
+  /** The question text the current `stuck` episode was opened on. */
+  episodeQuestion: string | null;
+  /** How many pings this episode has already emitted (first send = 1). */
+  sent: number;
+  /** When the next repeat is due, or null when nothing is scheduled. */
+  nextAt: number | null;
+}
+
+export function initialPingState(): PingState {
+  return {
+    state: null,
+    idleSince: null,
+    episode: null,
+    episodeQuestion: null,
+    sent: 0,
+    nextAt: null,
+  };
+}
+
+/** A decided ping, for the caller to deliver. */
+export interface PingDecision {
+  reason: PingReason;
+  /** 1 for the first ping of an episode, 2+ for a repeat nobody answered. */
+  attempt: number;
+  question: string | null;
+}
+
+/** Exponential backoff for repeat N (1-based), capped. */
+export function repeatDelayMs(attempt: number, cfg: PingConfig): number {
+  const raw = cfg.repeatBaseMs * 2 ** Math.max(0, attempt - 1);
+  return Math.min(raw, cfg.repeatMaxMs);
+}
+
+/**
+ * Advance by one tick. Returns the ping to send (or null) and the next state.
+ *
+ * Episode semantics:
+ *  - `needs_input` opens a `stuck` episode immediately. A CHANGED question
+ *    re-opens it (the agent is asking something new — that's fresh information,
+ *    not a repeat), which also resets the backoff.
+ *  - `idle` opens a `finished` episode only after `idleConfirmMs` of continuous
+ *    idleness — hysteresis, so a breath between tool calls is not "done".
+ *  - `exited` fires once, terminally, and cannot be superseded or repeated: the
+ *    process is gone, so there is nothing left to re-observe.
+ *  - `active` closes any open episode. The child is working again; whatever we
+ *    reported is stale and the parent will hear about the next edge.
+ */
+export function stepParentPing(
+  prev: PingState,
+  obs: PingObservation,
+  cfg: PingConfig = DEFAULT_PING_CONFIG,
+): { state: PingState; ping: PingDecision | null } {
+  const state: PingState = { ...prev };
+  const question = obs.question ?? null;
+  const wasExited = prev.episode === "exited";
+  state.state = obs.state;
+
+  // Terminal: once we've announced the exit there is nothing further to say.
+  if (wasExited) {
+    state.idleSince = null;
+    state.nextAt = null;
+    return { state, ping: null };
+  }
+
+  if (obs.state === "exited") {
+    state.idleSince = null;
+    state.episode = "exited";
+    state.episodeQuestion = null;
+    state.sent = 1;
+    state.nextAt = null;
+    return { state, ping: { reason: "exited", attempt: 1, question: null } };
+  }
+
+  if (obs.state === "active") {
+    // Working again — the episode (if any) is resolved or moot.
+    state.idleSince = null;
+    state.episode = null;
+    state.episodeQuestion = null;
+    state.sent = 0;
+    state.nextAt = null;
+    return { state, ping: null };
+  }
+
+  if (obs.state === "needs_input") {
+    state.idleSince = null;
+    const isNewEpisode = prev.episode !== "stuck" || prev.episodeQuestion !== question;
+    if (isNewEpisode) {
+      state.episode = "stuck";
+      state.episodeQuestion = question;
+      state.sent = 1;
+      state.nextAt = obs.now + repeatDelayMs(1, cfg);
+      return { state, ping: { reason: "stuck", attempt: 1, question } };
+    }
+    return repeatIfDue(state, obs.now, cfg, question);
+  }
+
+  // obs.state === "idle"
+  state.idleSince = prev.idleSince ?? obs.now;
+  if (prev.episode === "finished") return repeatIfDue(state, obs.now, cfg, null);
+  // A `stuck` episode that decayed into plain idle keeps its identity — the agent
+  // is still parked on the same unanswered thing, just no longer matching the
+  // question pattern (a menu that scrolled off the tail, say). Re-classifying it
+  // as `finished` would tell the parent "done" about an agent that is blocked.
+  if (prev.episode === "stuck") return repeatIfDue(state, obs.now, cfg, prev.episodeQuestion);
+  if (obs.now - state.idleSince < cfg.idleConfirmMs) return { state, ping: null };
+  state.episode = "finished";
+  state.episodeQuestion = null;
+  state.sent = 1;
+  state.nextAt = obs.now + repeatDelayMs(1, cfg);
+  return { state, ping: { reason: "finished", attempt: 1, question: null } };
+}
+
+/** Emit the next repeat of an already-open episode if its timer is due. */
+function repeatIfDue(
+  state: PingState,
+  now: number,
+  cfg: PingConfig,
+  question: string | null,
+): { state: PingState; ping: PingDecision | null } {
+  if (state.nextAt === null || now < state.nextAt) return { state, ping: null };
+  if (state.sent > cfg.maxRepeats) {
+    state.nextAt = null; // gave up nagging; the inbox/`ay ls` still shows the state
+    return { state, ping: null };
+  }
+  const attempt = state.sent + 1;
+  state.sent = attempt;
+  state.nextAt = attempt > cfg.maxRepeats ? null : now + repeatDelayMs(attempt, cfg);
+  return { state, ping: { reason: state.episode!, attempt, question } };
+}