agent-yes 1.169.1 → 1.170.1

package/ts/notifyRouter.spec.ts

@@ -0,0 +1,355 @@
+import { describe, expect, it } from "vitest";
+import { classifyNeedsInput } from "./needsInput.ts";
+import {
+  type ChildObservation,
+  type RouterState,
+  stepRouter,
+} from "./notifyRouter.ts";
+
+// Mirror the claude `needsInput`/`working` config (rs/default.config.yaml): the
+// menu cursor sits on a NUMBERED option, and a spinner marker means "working".
+const CFG = {
+  needsInput: [/❯ ?\d+\./m],
+  working: [/esc to interrupt/, /to run in background/],
+};
+
+const child = (over: Partial<ChildObservation> = {}): ChildObservation => ({
+  pid: 100,
+  wrapper_pid: 100,
+  started_at: 7000,
+  parent_pid: 1,
+  parent_started_at: 3000,
+  cli: "claude",
+  cwd: "/repo",
+  state: "active",
+  question: null,
+  ...over,
+});
+
+const step = (prev: RouterState, obs: ChildObservation[], now: number, idleConfirmMs = 30_000) =>
+  stepRouter(prev, obs, now, { idleConfirmMs });
+
+describe("notifyRouter — idle hysteresis (P1)", () => {
+  it("does NOT emit idle until the child has been idle for idleConfirmMs", () => {
+    let s: RouterState = new Map();
+    let r = step(s, [child({ state: "idle" })], 0);
+    expect(r.events).toEqual([]); // timer just started
+    s = r.next;
+
+    r = step(s, [child({ state: "idle" })], 10_000);
+    expect(r.events).toEqual([]); // still within the window
+    s = r.next;
+
+    r = step(s, [child({ state: "idle" })], 30_000);
+    expect(r.events.map((e) => e.edge)).toEqual(["idle"]); // confirmed
+    s = r.next;
+
+    r = step(s, [child({ state: "idle" })], 40_000);
+    expect(r.events).toEqual([]); // edge, not level — one per episode
+  });
+
+  it("treats active→idle→active→idle as two separate idle episodes", () => {
+    let s: RouterState = new Map();
+    s = step(s, [child({ state: "idle" })], 0).next;
+    s = step(s, [child({ state: "idle" })], 30_000).next; // episode 1 emits
+    // work resumes — resets the episode
+    s = step(s, [child({ state: "active" })], 35_000).next;
+    let r = step(s, [child({ state: "idle" })], 40_000);
+    expect(r.events).toEqual([]); // new episode, timer restarts
+    s = r.next;
+    r = step(s, [child({ state: "idle" })], 70_000);
+    expect(r.events.map((e) => e.edge)).toEqual(["idle"]); // episode 2 emits
+  });
+
+  it("a long silent working spell (state stays active) never emits idle", () => {
+    // The load-bearing guard: a 2-minute test run is `active`, not `idle`, so no
+    // amount of elapsed wall-clock produces a false idle edge.
+    let s: RouterState = new Map();
+    for (const t of [0, 30_000, 60_000, 120_000]) {
+      const r = step(s, [child({ state: "active" })], t);
+      expect(r.events).toEqual([]);
+      s = r.next;
+    }
+  });
+});
+
+describe("notifyRouter — needs_input", () => {
+  it("emits immediately on entering needs_input, with the question", () => {
+    const r = step(new Map(), [child({ state: "needs_input", question: "Approve? 1.Yes 2.No" })], 0);
+    expect(r.events).toHaveLength(1);
+    expect(r.events[0]!.edge).toBe("needs_input");
+    expect(r.events[0]!.question).toBe("Approve? 1.Yes 2.No");
+  });
+
+  it("does not re-fire while the same question stays on screen", () => {
+    let s: RouterState = new Map();
+    s = step(s, [child({ state: "needs_input", question: "Q1" })], 0).next;
+    const r = step(s, [child({ state: "needs_input", question: "Q1" })], 1_000);
+    expect(r.events).toEqual([]);
+  });
+
+  it("re-fires when the compact question changes (a genuinely new question)", () => {
+    let s: RouterState = new Map();
+    s = step(s, [child({ state: "needs_input", question: "Q1" })], 0).next;
+    const r = step(s, [child({ state: "needs_input", question: "Q2" })], 1_000);
+    expect(r.events.map((e) => e.edge)).toEqual(["needs_input"]);
+    expect(r.events[0]!.question).toBe("Q2");
+  });
+});
+
+describe("notifyRouter — exited", () => {
+  it("emits exactly once on stop", () => {
+    let s: RouterState = new Map();
+    let r = step(s, [child({ state: "stopped" })], 0);
+    expect(r.events.map((e) => e.edge)).toEqual(["exited"]);
+    s = r.next;
+    r = step(s, [child({ state: "stopped" })], 1_000);
+    expect(r.events).toEqual([]);
+  });
+
+  it("synthesizes an exited edge when a tracked child vanishes (reaped)", () => {
+    let s: RouterState = new Map();
+    s = step(s, [child({ state: "active" })], 0).next; // now tracked
+    const r = step(s, [], 1_000); // child gone from the live set
+    expect(r.events.map((e) => e.edge)).toEqual(["exited"]);
+    expect(r.events[0]!.child_pid).toBe(100);
+    // C2/I3: the synthetic exited must carry BOTH start times even though the
+    // child is gone from the current observation — else the pid-reuse guards
+    // (child on reconcile, parent on the read side) can't verify identity and
+    // a recycled pid's edge could be suppressed or mis-delivered.
+    expect(r.events[0]!.child_started_at).toBe(7000);
+    expect(r.events[0]!.parent_started_at).toBe(3000);
+    expect(r.next.has(100)).toBe(false); // forgotten
+  });
+
+  it("does not synthesize a second exited if we already emitted stopped", () => {
+    let s: RouterState = new Map();
+    s = step(s, [child({ state: "stopped" })], 0).next; // emitted exited
+    const r = step(s, [], 1_000); // then reaped
+    expect(r.events).toEqual([]);
+  });
+});
+
+describe("notifyRouter — routing scope", () => {
+  it("ignores children with no parent_pid (top-level agents)", () => {
+    const r = step(new Map(), [child({ state: "needs_input", parent_pid: 0, question: "Q" })], 0);
+    expect(r.events).toEqual([]);
+  });
+
+  it("addresses each edge to the child's parent_pid", () => {
+    const r = step(new Map(), [child({ state: "stopped", parent_pid: 42 })], 0);
+    expect(r.events[0]!.parent_pid).toBe(42);
+  });
+});
+
+// P1 regression: the real render the parent hit — a child parked at an idle
+// prompt with a RESOLVED prior menu lingering in scrollback must NOT be
+// misclassified as needs_input (which would mask the idle edge).
+describe("notifyRouter — idle-prompt fixture (P1 regression)", () => {
+  const idlePromptWithResolvedMenu = [
+    "  Do you want to proceed?",
+    "  1. Yes",
+    "  2. No, keep planning",
+    "  ⎿  Selected 1. Yes",
+    "",
+    "● Committed as abc1234 and pushed to origin/feat-x.",
+    "",
+    "╭──────────────────────────────────────────╮",
+    "│ > push it                                │",
+    "╰──────────────────────────────────────────╯",
+    "  ? for shortcuts",
+  ];
+
+  it("a resolved menu in scrollback is NOT needs_input (cursor not on a number)", () => {
+    // The numbered options linger but no `❯ N.` cursor remains — so the screen
+    // is quiet, classified idle, not needs_input.
+    expect(classifyNeedsInput(idlePromptWithResolvedMenu, CFG)).toBeNull();
+  });
+
+  it("an ACTIVE menu (cursor on a number) still classifies as needs_input", () => {
+    const activeMenu = [
+      "  Do you want to proceed?",
+      "❯ 1. Yes",
+      "  2. No, keep planning",
+    ];
+    expect(classifyNeedsInput(activeMenu, CFG)).not.toBeNull();
+  });
+
+  it("a working spinner wins over a lingering menu (no false needs_input)", () => {
+    const workingWithOldMenu = ["❯ 2. No, keep planning", "● Running tests… (esc to interrupt)"];
+    expect(classifyNeedsInput(workingWithOldMenu, CFG)).toBeNull();
+  });
+
+  it("end-to-end: such an idle child emits ONE idle edge after the confirm window", () => {
+    // Feeding the router the `idle` state (what deriveLiveState yields for the
+    // fixture above) produces exactly one idle edge per episode.
+    let s: RouterState = new Map();
+    s = step(s, [child({ state: "idle" })], 0).next;
+    const r = step(s, [child({ state: "idle" })], 30_000);
+    expect(r.events.map((e) => e.edge)).toEqual(["idle"]);
+  });
+});
+
+describe("notifyRouter — carry-forward vs exited (C2: watcher-lapse ≠ child-death)", () => {
+  it("carries forward an unobserved SAME child (alive, matching start time)", () => {
+    // Track a child, then a tick with NO observation of it but the SAME child
+    // still alive (matching started_at → parent's watcher merely lapsed).
+    let s: RouterState = new Map();
+    s = stepRouter(s, [child({ pid: 100, started_at: 7000, state: "active" })], 0).next;
+    const r = stepRouter(s, [], 1_000, { aliveChildStartedAt: new Map([[100, 7000]]) });
+    expect(r.events).toEqual([]); // no false exited
+    expect(r.next.has(100)).toBe(true); // carried forward
+    expect(r.next.get(100)!.started_at).toBe(7000); // identity preserved
+  });
+
+  it("synthesizes exited when the child's pid is not alive at all", () => {
+    let s: RouterState = new Map();
+    s = stepRouter(s, [child({ pid: 100, state: "active" })], 0).next;
+    const r = stepRouter(s, [], 1_000, { aliveChildStartedAt: new Map() }); // pid dead
+    expect(r.events.map((e) => e.edge)).toEqual(["exited"]);
+    expect(r.events[0]!.child_started_at).toBe(7000);
+  });
+
+  it("synthesizes exited IMMEDIATELY when the pid is reused by a different child during a lapse", () => {
+    // The identity-aware fix: pid 100 is alive but its start time now differs
+    // (7000 → 9000) — the old child died and its pid was reused. We must NOT
+    // carry it forward as if still running; emit the old child's exited now, no
+    // waiting for the watcher to return.
+    let s: RouterState = new Map();
+    s = stepRouter(s, [child({ pid: 100, started_at: 7000, state: "active" })], 0).next;
+    const r = stepRouter(s, [], 1_000, { aliveChildStartedAt: new Map([[100, 9000]]) });
+    expect(r.events.map((e) => e.edge)).toEqual(["exited"]);
+    expect(r.events[0]!.child_started_at).toBe(7000); // the OLD child's identity
+    expect(r.next.has(100)).toBe(false); // dropped
+  });
+
+  it("recovers the old child's exited on watcher RETURN (same-child lapse then reuse)", () => {
+    // Child tracked; watcher lapses with the SAME child still alive (carried);
+    // when the watcher returns, the pid is observed with a NEW start time → the
+    // old child's exited is recovered by the hot-path guard, new child fresh.
+    let s: RouterState = new Map();
+    s = stepRouter(s, [child({ pid: 100, started_at: 1000, state: "idle" })], 0).next;
+    s = stepRouter(s, [], 1_000, { aliveChildStartedAt: new Map([[100, 1000]]) }).next; // carried
+    const r = stepRouter(
+      s,
+      [child({ pid: 100, started_at: 2000, state: "needs_input", question: "New?" })],
+      2_000,
+    );
+    const edges = r.events.map((e) => e.edge);
+    expect(edges).toContain("exited"); // old child (1000) recovered
+    expect(r.events.find((e) => e.edge === "exited")!.child_started_at).toBe(1000);
+    expect(edges).toContain("needs_input"); // new child (2000) fresh
+    expect(r.next.get(100)!.started_at).toBe(2000);
+  });
+});
+
+describe("notifyRouter — hot-path pid reuse (Important)", () => {
+  it("treats a same-pid child with a NEW start time as a fresh child", () => {
+    // Old child exits at pid 100; then pid 100 is recycled by a NEW child that
+    // goes needs_input. The new child's needs_input must fire (not be suppressed
+    // by the old child's state), and the old child gets a synthetic exited.
+    let s: RouterState = new Map();
+    s = step(s, [child({ pid: 100, started_at: 1000, state: "idle" })], 0).next;
+    s = step(s, [child({ pid: 100, started_at: 1000, state: "idle" })], 30_000).next; // old idle-emitted
+    const r = step(
+      s,
+      [child({ pid: 100, started_at: 2000, state: "needs_input", question: "New?" })],
+      31_000,
+    );
+    const edges = r.events.map((e) => e.edge);
+    expect(edges).toContain("exited"); // old child (started_at 1000) closed out
+    expect(edges).toContain("needs_input"); // new child (started_at 2000) fires
+    expect(r.events.find((e) => e.edge === "exited")!.child_started_at).toBe(1000);
+    expect(r.events.find((e) => e.edge === "needs_input")!.child_started_at).toBe(2000);
+    // The next state reflects the NEW child only.
+    expect(r.next.get(100)!.started_at).toBe(2000);
+    expect(r.next.get(100)!.exitedEmitted).toBe(false);
+  });
+
+  it("does NOT inherit emitted-memory from a tracked state with no start time (fail-safe)", () => {
+    // Old state seeded WITHOUT a start time (unverifiable). A same-pid child now
+    // observed with a start time must NOT inherit idleEmitted/exitedEmitted — else
+    // its first edge is suppressed. It rebuilds fresh (a duplicate is acceptable),
+    // and NO synthetic exited is emitted (it may be the same child).
+    const seeded: RouterState = new Map([
+      [
+        100,
+        {
+          parent_pid: 1,
+          started_at: undefined, // unverifiable
+          cli: "claude",
+          cwd: "/repo",
+          state: "idle",
+          idleSince: 0,
+          idleEmitted: true, // already emitted for the OLD episode
+          inNeedsInput: false,
+          needsInputQuestion: null,
+          exitedEmitted: false,
+        },
+      ],
+    ]);
+    const r = stepRouter(seeded, [child({ pid: 100, started_at: 5000, state: "idle" })], 0, {
+      idleConfirmMs: 30_000,
+    });
+    expect(r.events.some((e) => e.edge === "exited")).toBe(false); // no false exited
+    expect(r.next.get(100)!.idleEmitted).toBe(false); // fresh — not inherited
+    expect(r.next.get(100)!.started_at).toBe(5000);
+  });
+
+  it("does not double-close an old child that had already exited", () => {
+    let s: RouterState = new Map();
+    s = step(s, [child({ pid: 100, started_at: 1000, state: "stopped" })], 0).next; // exited emitted
+    const r = step(s, [child({ pid: 100, started_at: 2000, state: "idle" })], 1_000);
+    // Old child already exited → no second exited; new child just starts its idle timer.
+    expect(r.events).toEqual([]);
+    expect(r.next.get(100)!.started_at).toBe(2000);
+  });
+});
+
+describe("notifyRouter — startup reconcile (baseline)", () => {
+  it("emits needs_input immediately for a child already blocked at daemon start", () => {
+    const r = step(new Map(), [child({ state: "needs_input", question: "Q" })], 5_000);
+    expect(r.events.map((e) => e.edge)).toEqual(["needs_input"]);
+  });
+
+  it("emits exited immediately for a child already stopped at daemon start", () => {
+    const r = step(new Map(), [child({ state: "stopped" })], 5_000);
+    expect(r.events.map((e) => e.edge)).toEqual(["exited"]);
+  });
+
+  it("a child already idle at start emits only after the confirm window (from now)", () => {
+    let s: RouterState = new Map();
+    let r = step(s, [child({ state: "idle" })], 5_000);
+    expect(r.events).toEqual([]); // timer anchored at first observation
+    s = r.next;
+    r = step(s, [child({ state: "idle" })], 35_000);
+    expect(r.events.map((e) => e.edge)).toEqual(["idle"]);
+  });
+
+  it("respects a SEEDED prior state (no duplicate baseline across daemon restart)", () => {
+    // The daemon seeds prior emitted state from the inbox so a restart doesn't
+    // re-emit. A seeded exitedEmitted child that is still `stopped` stays quiet —
+    // the seed carries the SAME start time as the observation, so the identity is
+    // verifiable and the emitted-memory is (correctly) inherited.
+    const seeded: RouterState = new Map([
+      [
+        100,
+        {
+          parent_pid: 1,
+          wrapper_pid: 100,
+          started_at: 7000, // matches the child() factory → verifiable identity
+          cli: "claude",
+          cwd: "/repo",
+          state: "stopped",
+          idleSince: null,
+          idleEmitted: false,
+          inNeedsInput: false,
+          needsInputQuestion: null,
+          exitedEmitted: true,
+        },
+      ],
+    ]);
+    const r = step(seeded, [child({ state: "stopped" })], 0);
+    expect(r.events).toEqual([]);
+  });
+});

package/ts/notifyRouter.ts

@@ -0,0 +1,288 @@
+/**
+ * Pure edge-detection + debounce state machine for subagent→parent
+ * notifications. The heart of `ay notifyd`: given each tick's observed child
+ * states, decide which EDGES to push to which parent, exactly once per episode,
+ * without spamming on transient flicker.
+ *
+ * Design (frozen with codex + the two agents who hit the pain):
+ *  - Signal is the query-layer `deriveLiveState` state — NOT a bare no-output
+ *    timer. `idle` already means "idle prompt visible AND no working spinner",
+ *    so a long, silent tool call (a 2-minute test run) is classified `active`
+ *    and never produces a false idle edge. This is the load-bearing P1 guard.
+ *  - Three edges, child→parent only (never cascade a parent's own state):
+ *      needs_input : immediate; re-fire only when the COMPACT question changes.
+ *      exited      : immediate, once.
+ *      idle        : only after the child has been continuously `idle` for
+ *                    `idleConfirmMs` (hysteresis), once per idle episode.
+ *  - Edge, not level: a state that stays idle emits one edge, not one per tick.
+ *  - Reaped-child safety: a child that vanishes from the live set without our
+ *    seeing `stopped` gets a synthetic `exited` (mirrors `diffLsStates`).
+ *
+ * Pure + synchronous (no clock, no fs — the caller passes `now`) so it is
+ * trivially unit-testable, like `lsWatch.ts` / `needsInput.ts`. The poll loop,
+ * inbox writes, payload enrichment, and startup reconcile live in
+ * `subcommands.ts` (`cmdNotifyd`); persistence lives in `notifyInbox.ts`.
+ */
+
+import type { NotifyEdge } from "./notifyInbox.ts";
+
+/** One child's observed state this tick (from `deriveLiveState` + the registry). */
+export interface ChildObservation {
+  pid: number;
+  wrapper_pid?: number;
+  /** The child's own start time — carried into events for the pid-reuse guard. */
+  started_at?: number;
+  /** The parent this child links to (parent wrapper pid). Required to route. */
+  parent_pid: number;
+  /** The parent's start time — carried so a synthetic exited keeps the parent guard. */
+  parent_started_at?: number;
+  cli: string;
+  cwd: string;
+  /** `deriveLiveState` state: active | idle | stopped | needs_input | stuck. */
+  state: string;
+  /** Compact question when state === "needs_input", else null. */
+  question: string | null;
+}
+
+/** A decided notification, before the daemon enriches it (seq/ts/tail/git). */
+export interface PendingNotification {
+  parent_pid: number;
+  child_pid: number;
+  child_wrapper_pid?: number;
+  /** The child's start time (from the observation / carried state). */
+  child_started_at?: number;
+  /** The parent's start time (from the observation / carried state). */
+  parent_started_at?: number;
+  cli: string;
+  cwd: string;
+  edge: NotifyEdge;
+  prev_state: string | null;
+  state: string;
+  question: string | null;
+}
+
+/** Per-child debounce memory, carried across ticks. */
+export interface ChildRouterState {
+  parent_pid: number;
+  wrapper_pid?: number;
+  /** The child's start time — so a synthetic exited (child already gone) keeps it. */
+  started_at?: number;
+  /** The parent's start time — carried so a synthetic exited keeps the parent guard. */
+  parent_started_at?: number;
+  cli: string;
+  cwd: string;
+  /** Last observed state. */
+  state: string;
+  /** When the current idle episode began (ms), or null if not idle. */
+  idleSince: number | null;
+  /** Whether we already emitted the idle edge for the current episode. */
+  idleEmitted: boolean;
+  /** Whether we are inside a needs_input episode we've emitted at least once. */
+  inNeedsInput: boolean;
+  /** The compact question of the last emitted needs_input (for change re-fire). */
+  needsInputQuestion: string | null;
+  /** Whether we already emitted the exited edge for this child. */
+  exitedEmitted: boolean;
+}
+
+export type RouterState = Map<number, ChildRouterState>;
+
+export interface RouterConfig {
+  /** How long a child must stay continuously idle before we emit an idle edge. */
+  idleConfirmMs: number;
+  /**
+   * pid → started_at for every child ACTUALLY ALIVE right now (from the registry).
+   * A tracked child that drops out of this tick's observations is carried forward
+   * (not false-exited) ONLY when the live pid's start time still MATCHES the
+   * tracked one — i.e. it is the SAME child, merely unobserved (its parent's
+   * watcher lapsed). If the pid is alive but with a DIFFERENT start time, the old
+   * child died and its pid was reused during the lapse → synthesize its exited
+   * immediately (identity-aware, no waiting for the watcher to return). If the
+   * tracked start time is unknown (rare), fall back to liveness-only carry-forward
+   * to avoid a false exited. When omitted entirely, any unobserved tracked child
+   * is treated as exited (the caller has no liveness info).
+   */
+  aliveChildStartedAt?: Map<number, number>;
+}
+
+const DEFAULT_IDLE_CONFIRM_MS = 30_000;
+
+/**
+ * Advance the router by one tick. Returns the notifications to push plus the
+ * next RouterState. Only children with a numeric `parent_pid` are considered —
+ * the caller is responsible for including only opted-in children.
+ *
+ * First-observation (baseline / startup-reconcile) semantics: a child we've
+ * never seen that is ALREADY terminal emits immediately for `needs_input` /
+ * `stopped`, and starts its idle timer at `now` for `idle` (so a child parked
+ * idle when the daemon starts still notifies after the confirm window). To avoid
+ * re-emitting the same baseline on every daemon restart, the caller SEEDS the
+ * prior state from each inbox's already-written edges (see cmdNotifyd).
+ */
+export function stepRouter(
+  prev: RouterState,
+  observations: ChildObservation[],
+  now: number,
+  config: Partial<RouterConfig> = {},
+): { events: PendingNotification[]; next: RouterState } {
+  const idleConfirmMs = config.idleConfirmMs ?? DEFAULT_IDLE_CONFIRM_MS;
+  const events: PendingNotification[] = [];
+  const next: RouterState = new Map();
+  const seen = new Set<number>();
+
+  for (const obs of observations) {
+    if (typeof obs.parent_pid !== "number" || obs.parent_pid <= 0) continue;
+    seen.add(obs.pid);
+    let p = prev.get(obs.pid);
+    // Hot-path pid-reuse guard (mirrors the startup reconcile guard). Two cases,
+    // both fail-safe — an unverifiable identity is NEVER inherited:
+    //  1. CONFIRMED reuse: both start times known and different → the old child
+    //     is gone. `seen` marks the pid so the vanished-loop won't fire; emit its
+    //     synthetic exited here, then drop `p` so the new child rebuilds fresh.
+    //  2. UNVERIFIABLE: the observation has a start time but the tracked state has
+    //     none (e.g. seeded without one). We can't confirm it's the same child,
+    //     so we DON'T inherit its emitted-edge memory (a re-emit / duplicate is
+    //     safe; a suppressed first edge is not) — but we also DON'T synthesize an
+    //     exited, since it may well be the same child (avoid a false exited).
+    if (p && obs.started_at != null && p.started_at != null && p.started_at !== obs.started_at) {
+      if (!p.exitedEmitted) events.push(syntheticExited(p, obs.pid));
+      p = undefined;
+    } else if (p && obs.started_at != null && p.started_at == null) {
+      p = undefined; // unverifiable — rebuild fresh, no inherit, no synthetic exited
+    }
+    const cs: ChildRouterState = {
+      parent_pid: obs.parent_pid,
+      wrapper_pid: obs.wrapper_pid,
+      started_at: obs.started_at,
+      parent_started_at: obs.parent_started_at,
+      cli: obs.cli,
+      cwd: obs.cwd,
+      state: obs.state,
+      idleSince: p?.idleSince ?? null,
+      idleEmitted: p?.idleEmitted ?? false,
+      inNeedsInput: p?.inNeedsInput ?? false,
+      needsInputQuestion: p?.needsInputQuestion ?? null,
+      exitedEmitted: p?.exitedEmitted ?? false,
+    };
+    const prevState = p?.state ?? null;
+    const emit = (edge: NotifyEdge) =>
+      events.push({
+        parent_pid: obs.parent_pid,
+        child_pid: obs.pid,
+        child_wrapper_pid: obs.wrapper_pid,
+        child_started_at: obs.started_at,
+        parent_started_at: obs.parent_started_at,
+        cli: obs.cli,
+        cwd: obs.cwd,
+        edge,
+        prev_state: prevState,
+        state: obs.state,
+        question: edge === "needs_input" ? obs.question : null,
+      });
+
+    switch (obs.state) {
+      case "needs_input": {
+        // Leaving idle/other → reset those episodes.
+        cs.idleSince = null;
+        cs.idleEmitted = false;
+        // Fire on entry, or when the compact question changed (a NEW question).
+        // Compare the compact (chrome-stripped) question so a spinner/elapsed-
+        // seconds cosmetic redraw doesn't double-fire.
+        if (!cs.inNeedsInput || cs.needsInputQuestion !== obs.question) {
+          emit("needs_input");
+          cs.inNeedsInput = true;
+          cs.needsInputQuestion = obs.question;
+        }
+        break;
+      }
+      case "idle": {
+        cs.inNeedsInput = false;
+        cs.needsInputQuestion = null;
+        // Continue the episode if we were already idle; else start it now.
+        if (p?.state === "idle" && p.idleSince != null) {
+          cs.idleSince = p.idleSince;
+          cs.idleEmitted = p.idleEmitted;
+        } else {
+          cs.idleSince = now;
+          cs.idleEmitted = false;
+        }
+        if (!cs.idleEmitted && now - (cs.idleSince ?? now) >= idleConfirmMs) {
+          emit("idle");
+          cs.idleEmitted = true;
+        }
+        break;
+      }
+      case "stopped": {
+        cs.idleSince = null;
+        cs.idleEmitted = false;
+        cs.inNeedsInput = false;
+        cs.needsInputQuestion = null;
+        if (!cs.exitedEmitted) {
+          emit("exited");
+          cs.exitedEmitted = true;
+        }
+        break;
+      }
+      // "active", "stuck", or any unknown busy state: real work (or a wedge) is
+      // happening — reset the idle/needs_input episodes so a later idle counts
+      // as a fresh episode, and emit nothing.
+      default: {
+        cs.idleSince = null;
+        cs.idleEmitted = false;
+        cs.inNeedsInput = false;
+        cs.needsInputQuestion = null;
+        break;
+      }
+    }
+
+    next.set(obs.pid, cs);
+  }
+
+  // Reaped-child safety: a child we were tracking dropped out of the live set
+  // without our observing `stopped`. Synthesize one exited edge (once) so a
+  // "done" transition is never dropped, then forget it.
+  for (const [pid, cs] of prev) {
+    if (seen.has(pid)) continue;
+    // Distinguish "child died" from "child merely not observed this tick" (its
+    // parent's watcher lapsed, so it fell out of the observed scope) — and do it
+    // IDENTITY-AWARE, so a pid reused during the lapse doesn't masquerade as the
+    // same still-running child. Carry forward only when the SAME child is still
+    // alive (live start time matches, or the tracked start time is unknown —
+    // fail-safe against a false exited). Otherwise the child is gone (dead, or its
+    // pid now belongs to a different child) → synthesize its exited.
+    if (config.aliveChildStartedAt) {
+      const liveStart = config.aliveChildStartedAt.get(pid);
+      const sameChildAlive =
+        liveStart !== undefined && (cs.started_at == null || liveStart === cs.started_at);
+      if (sameChildAlive) {
+        next.set(pid, cs);
+        continue;
+      }
+    }
+    if (!cs.exitedEmitted) events.push(syntheticExited(cs, pid));
+    // Dead & gone (or pid reused) — drop from the tracked set.
+  }
+
+  return { events, next };
+}
+
+/**
+ * A synthetic `exited` for a child that left the live set without our observing
+ * its stop — either reaped between ticks, or displaced by a pid-reuse. Built from
+ * the last-known router state so it still carries the child's identity.
+ */
+function syntheticExited(cs: ChildRouterState, pid: number): PendingNotification {
+  return {
+    parent_pid: cs.parent_pid,
+    child_pid: pid,
+    child_wrapper_pid: cs.wrapper_pid,
+    child_started_at: cs.started_at,
+    parent_started_at: cs.parent_started_at,
+    cli: cs.cli,
+    cwd: cs.cwd,
+    edge: "exited",
+    prev_state: cs.state,
+    state: "stopped",
+    question: null,
+  };
+}