@selesai/code 0.13.38 → 0.13.40

package/dist/extensions/pi-intercom/release-readiness.test.ts

@@ -0,0 +1,116 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { intercomReleaseBlockers, stopIntercom, type IntercomStopState } from "./release-readiness.ts";
+import { ReplyTracker } from "./reply-tracker.ts";
+import type { Message, SessionInfo } from "./types.ts";
+
+function createSession(id: string, name?: string): SessionInfo {
+  return { id, name, cwd: "/tmp/project", model: "test-model", pid: 1, startedAt: 1, lastActivity: 1 };
+}
+
+function createMessage(id: string, expectsReply: boolean): Message {
+  return { id, timestamp: 1, expectsReply, content: { text: "hello" } };
+}
+
+const idle = { pendingAsks: [], outboundAsk: null, pendingOutboxRequests: 0 };
+
+test("an idle intercom has no release blockers", () => {
+  assert.deepEqual(intercomReleaseBlockers(idle), []);
+});
+
+test("unanswered inbound asks block; plain messages and answered asks do not", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", true), 1000);
+  tracker.recordIncomingMessage(createSession("other-id"), createMessage("ask-2", true), 2000);
+  tracker.recordIncomingMessage(createSession("fyi-id", "fyi"), createMessage("note-1", false), 1500);
+  assert.deepEqual(intercomReleaseBlockers({ ...idle, pendingAsks: tracker.listPending(2500) }), [
+    { source: "intercom", kind: "inbound_ask", id: "ask-1", detail: "Ask from planner is awaiting our reply", since: 1000 },
+    { source: "intercom", kind: "inbound_ask", id: "ask-2", detail: "Ask from other-id is awaiting our reply", since: 2000 },
+  ]);
+  tracker.markReplied("ask-1");
+  assert.deepEqual(intercomReleaseBlockers({ ...idle, pendingAsks: tracker.listPending(2500) }).map(blocker => blocker.id), ["ask-2"]);
+});
+
+test("a blocking outbound ask is reported with its reply id and start time", () => {
+  assert.deepEqual(intercomReleaseBlockers({ ...idle, outboundAsk: { from: "planner", replyTo: "reply-9", startedAt: 4242 } }), [
+    { source: "intercom", kind: "outbound_ask", id: "reply-9", detail: "Blocking ask to planner is awaiting a reply", since: 4242 },
+  ]);
+  // A missing start time is omitted rather than invented.
+  const [blocker] = intercomReleaseBlockers({ ...idle, outboundAsk: { from: "planner", replyTo: "reply-9" } });
+  assert.equal("since" in blocker!, false);
+});
+
+test("unsettled outbox requests block", () => {
+  assert.deepEqual(intercomReleaseBlockers({ ...idle, pendingOutboxRequests: 2 }), [
+    { source: "intercom", kind: "outbound_message", detail: "2 outbound message request(s) have not settled" },
+  ]);
+});
+
+test("blockers are bounded and never carry invalid timestamps", () => {
+  const long = "x".repeat(600);
+  const [blocker] = intercomReleaseBlockers({
+    ...idle,
+    pendingAsks: [{ from: createSession("id", long), message: createMessage(long, true), receivedAt: Number.NaN }],
+  });
+  assert.equal(blocker!.id!.length, 256);
+  assert.equal(blocker!.detail.length, 512);
+  assert.equal("since" in blocker!, false);
+});
+
+const farDeadline = () => Date.now() + 5_000;
+const stopState = (overrides: Partial<IntercomStopState> = {}): IntercomStopState => ({ pendingAsks: [], outboundAsk: null, cancelOutboundAsk: () => undefined, ...overrides });
+
+test("stop: an idle intercom has nothing to stop", () => {
+  assert.deepEqual(stopIntercom(stopState(), { deadline: farDeadline() }), []);
+});
+
+test("stop: cancels the blocking outbound ask through the client cancel and reports it", () => {
+  const cancelled: Array<{ from: string; replyTo: string }> = [];
+  const items = stopIntercom(
+    stopState({ outboundAsk: { from: "planner", replyTo: "reply-9", startedAt: 1 }, cancelOutboundAsk: ask => { cancelled.push(ask); } }),
+    { deadline: farDeadline() },
+  );
+  assert.deepEqual(cancelled, [{ from: "planner", replyTo: "reply-9" }]);
+  assert.deepEqual(items, [{ source: "intercom", kind: "outbound_ask", id: "reply-9", detail: "Cancelled blocking ask to planner", ok: true }]);
+});
+
+test("stop: reports a failing cancel as ok:false instead of throwing", () => {
+  const items = stopIntercom(
+    stopState({ outboundAsk: { from: "planner", replyTo: "reply-9" }, cancelOutboundAsk: () => { throw new Error("socket closed"); } }),
+    { deadline: farDeadline() },
+  );
+  assert.deepEqual(items, [{ source: "intercom", kind: "outbound_ask", id: "reply-9", detail: "Failed to cancel blocking ask to planner: socket closed", ok: false, error: "socket closed" }]);
+});
+
+test("stop: inbound asks cannot be cancelled by the receiver and are reported ok:false, left untouched", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", true), 1000);
+  tracker.recordIncomingMessage(createSession("fyi-id", "fyi"), createMessage("note-1", false), 1500);
+  const items = stopIntercom(stopState({ pendingAsks: tracker.listPending(2000) }), { deadline: farDeadline() });
+  assert.deepEqual(items, [{
+    source: "intercom", kind: "inbound_ask", id: "ask-1",
+    detail: "cannot cancel inbound: ask from planner is awaiting our reply and keeps waiting", ok: false, error: "cannot cancel inbound",
+  }]);
+  assert.equal(tracker.listPending(2000).length, 1, "the ask is still pending");
+});
+
+test("stop: appends the recipient-side outcome when the best-effort message cancel settles within the deadline", async () => {
+  const items = await stopIntercom(
+    stopState({ outboundAsk: { from: "planner", replyTo: "reply-9" }, cancelOutboundAsk: () => Promise.resolve("recipient asked to drop it") }),
+    { deadline: farDeadline() },
+  );
+  assert.deepEqual(items, [{ source: "intercom", kind: "outbound_ask", id: "reply-9", detail: "Cancelled blocking ask to planner; recipient asked to drop it", ok: true }]);
+});
+
+test("stop: a hanging or rejecting recipient-side cancel does not change the result or outlive the deadline", async () => {
+  const hanging = await stopIntercom(
+    stopState({ outboundAsk: { from: "planner", replyTo: "reply-9" }, cancelOutboundAsk: () => new Promise<string>(() => undefined) }),
+    { deadline: Date.now() + 40 },
+  );
+  assert.deepEqual(hanging.map(item => [item.kind, item.ok, item.detail]), [["outbound_ask", true, "Cancelled blocking ask to planner"]]);
+  const rejecting = await stopIntercom(
+    stopState({ outboundAsk: { from: "planner", replyTo: "reply-9" }, cancelOutboundAsk: () => Promise.reject(new Error("Cancel timeout")) }),
+    { deadline: farDeadline() },
+  );
+  assert.deepEqual(rejecting.map(item => [item.kind, item.ok]), [["outbound_ask", true]]);
+});

package/dist/extensions/pi-intercom/release-readiness.ts

@@ -0,0 +1,93 @@
+import type { ReleaseBlocker, StopAllBackgroundItem } from "@selesai/code";
+import type { IntercomContext } from "./reply-tracker.ts";
+
+export interface IntercomReleaseState {
+  /** Inbound asks still awaiting OUR reply (`ReplyTracker.listPending()`). */
+  pendingAsks: readonly IntercomContext[];
+  /** The module-level blocking outbound ask (`replyWaiter`), if one is in flight. */
+  outboundAsk: { from: string; replyTo: string; startedAt?: number } | null;
+  /** Outbound outbox requests from other extensions that have not settled. */
+  pendingOutboxRequests: number;
+}
+
+const clip = (value: string, max: number) => value.length > max ? value.slice(0, max) : value;
+
+/** Release blockers owned by the intercom extension. Pure: callers pass a snapshot of live state. */
+export function intercomReleaseBlockers(state: IntercomReleaseState): ReleaseBlocker[] {
+  const blockers: ReleaseBlocker[] = [];
+  for (const ask of state.pendingAsks) {
+    const sender = ask.from.name?.trim() || ask.from.id;
+    blockers.push({
+      source: "intercom", kind: "inbound_ask", id: clip(ask.message.id, 256),
+      detail: clip(`Ask from ${sender} is awaiting our reply`, 512),
+      ...(Number.isFinite(ask.receivedAt) && ask.receivedAt >= 0 ? { since: Math.trunc(ask.receivedAt) } : {}),
+    });
+  }
+  if (state.outboundAsk) {
+    const { from, replyTo, startedAt } = state.outboundAsk;
+    blockers.push({
+      source: "intercom", kind: "outbound_ask", id: clip(replyTo, 256),
+      detail: clip(`Blocking ask to ${from} is awaiting a reply`, 512),
+      ...(startedAt !== undefined && Number.isFinite(startedAt) && startedAt >= 0 ? { since: Math.trunc(startedAt) } : {}),
+    });
+  }
+  if (state.pendingOutboxRequests > 0) {
+    blockers.push({ source: "intercom", kind: "outbound_message", detail: `${state.pendingOutboxRequests} outbound message request(s) have not settled` });
+  }
+  return blockers;
+}
+
+export interface IntercomStopState {
+  /** Inbound asks still awaiting OUR reply (`ReplyTracker.listPending()`). */
+  pendingAsks: readonly IntercomContext[];
+  /** The module-level blocking outbound ask (`replyWaiter`), if one is in flight. */
+  outboundAsk: { from: string; replyTo: string; startedAt?: number } | null;
+  /**
+   * Cancels the outbound ask: tells the broker (`client.cancelAsk`, drops the ask edge and its pending-ask record) and rejects the
+   * local waiter so the blocked tool call returns. Synchronous. Optionally returns the settled outcome of asking the recipient to
+   * drop the message (`client.cancelMessage`); that part is best-effort because the recipient may already have acted on it.
+   */
+  cancelOutboundAsk(ask: { from: string; replyTo: string }): void | PromiseLike<string | undefined>;
+}
+
+/**
+ * Kill-switch handler. Outbound asks have a cancel (broker `cancel_ask` / `cancel_message`, exposed by the client), so they are
+ * cancelled. Inbound asks waiting on THIS session cannot be cancelled by the receiver (the protocol has no "decline"), so they are
+ * left alone and reported as `ok:false` so the caller can show who is still waiting. Never throws.
+ */
+export function stopIntercom(state: IntercomStopState, request: { deadline: number }, now: () => number = Date.now): StopAllBackgroundItem[] | PromiseLike<StopAllBackgroundItem[]> {
+  const items: StopAllBackgroundItem[] = [];
+  let pendingCancel: PromiseLike<string | undefined> | undefined;
+  const ask = state.outboundAsk;
+  let outbound: StopAllBackgroundItem | undefined;
+  if (ask) {
+    const base = { source: "intercom", kind: "outbound_ask", id: clip(ask.replyTo, 256) };
+    try {
+      const outcome = state.cancelOutboundAsk({ from: ask.from, replyTo: ask.replyTo });
+      outbound = { ...base, detail: clip(`Cancelled blocking ask to ${ask.from}`, 512), ok: true };
+      if (outcome) pendingCancel = outcome;
+    } catch (error) {
+      const text = error instanceof Error ? error.message : String(error);
+      outbound = { ...base, detail: clip(`Failed to cancel blocking ask to ${ask.from}: ${text}`, 512), ok: false, error: clip(text, 256) };
+    }
+    items.push(outbound);
+  }
+  for (const inbound of state.pendingAsks) {
+    const sender = inbound.from.name?.trim() || inbound.from.id;
+    items.push({
+      source: "intercom", kind: "inbound_ask", id: clip(inbound.message.id, 256),
+      detail: clip(`cannot cancel inbound: ask from ${sender} is awaiting our reply and keeps waiting`, 512), ok: false, error: "cannot cancel inbound",
+    });
+  }
+  if (!pendingCancel || !outbound) return items;
+  const finished = outbound;
+  const budget = Math.max(0, request.deadline - now());
+  return new Promise<StopAllBackgroundItem[]>((resolve) => {
+    const timer = setTimeout(() => resolve(items), budget);
+    pendingCancel!.then((note) => {
+      clearTimeout(timer);
+      if (note) finished.detail = clip(`${finished.detail}; ${note}`, 512);
+      resolve(items);
+    }, () => { clearTimeout(timer); resolve(items); });
+  });
+}

package/dist/extensions/pi-subagents/docs/extension-api.md

@@ -546,3 +546,11 @@ The main runtime files in this repository:
 | `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
 | `src/extension/schemas.ts` / `src/shared/types.ts` | Tool schemas, shared types, and event constants. |
 | `test/unit/` / `test/integration/` | Unit and loader-based integration tests. |
+
+## Desktop stdio observation v1
+
+Headless/Desktop clients can send `{"type":"subagent_status","id":"status-1","version":1}` directly, without a model turn. The response's `data` contains `{version:1,available,capabilities:{snapshot:true,events},sessionId,epoch,revision,fleet,runs,omitted:{runs,children}}`. Missing backend is explicitly `available:false`; unsupported/missing versions fail. This read-only stdio contract does not expose spawn, management, steering, or stop.
+
+`subagent_event` carries `{version:1,sessionId,epoch,revision,snapshot:<same data>}` after binding and on coalesced native state changes, even while the parent is idle. Always full-replace, not patch. The host session ID is a bare SDK ID; the binding epoch is shared with Intercom's nested `scope` and rotates on switch/reload. Discard obsolete scopes/revisions, request fresh status after reconnect, and never treat parent `agent_end` as child completion.
+
+Opaque node keys are epoch-local, never filesystem paths; run/workflow identities appear only when native records supply them. Lifecycle status, optional actual supervisor-wait/control activity, task outcome, and process-terminal proof remain separate. No success, exit, timestamps, or missing node usage are fabricated. Native tracker-fed state is reused; this adapter performs no artifact scans or executor calls. Runs/recent history are bounded, not a permanent ledger: 32 roots, 64 nodes, 16 immediate children, depth 4, 64 KiB including envelope reserve; omission counts describe only excluded candidates in this display window. Fleet uses its existing 16-entry projection. See the [exact stdio schema and examples](../../../../docs/rpc.md#subagent-observability-desktop--headless-clients) and [JSON Schema](../../../../docs/rpc-subagent.schema.json).

package/dist/extensions/pi-subagents/docs/observability.md

@@ -303,3 +303,11 @@ Intercom delivery events:
 `src/extension/index.ts` registers the notification handler that consumes `subagent:async-complete`. Control/attention events are surfaced as visible parent notices and persisted for async runs. Native supervisor requests are delivered only to the exact parent session that spawned the child.
 
 `pi.events` is in-process only. It does not reach separate Pi processes or child subagents; use the file lifecycle artifacts or `pi-intercom` for cross-process coordination.
+
+## Desktop stdio observation v1
+
+Headless/Desktop clients can send `{"type":"subagent_status","id":"status-1","version":1}` directly, without a model turn. The response's `data` contains `{version:1,available,capabilities:{snapshot:true,events},sessionId,epoch,revision,fleet,runs,omitted:{runs,children}}`. Missing backend is explicitly `available:false`; unsupported/missing versions fail. This read-only stdio contract does not expose spawn, management, steering, or stop.
+
+`subagent_event` carries `{version:1,sessionId,epoch,revision,snapshot:<same data>}` after binding and on coalesced native state changes, even while the parent is idle. Always full-replace, not patch. The host session ID is a bare SDK ID; the binding epoch is shared with Intercom's nested `scope` and rotates on switch/reload. Discard obsolete scopes/revisions, request fresh status after reconnect, and never treat parent `agent_end` as child completion.
+
+Opaque node keys are epoch-local, never filesystem paths; run/workflow identities appear only when native records supply them. Lifecycle status, optional actual supervisor-wait/control activity, task outcome, and process-terminal proof remain separate. No success, exit, timestamps, or missing node usage are fabricated. Native tracker-fed state is reused; this adapter performs no artifact scans or executor calls. Runs/recent history are bounded, not a permanent ledger: 32 roots, 64 nodes, 16 immediate children, depth 4, 64 KiB including envelope reserve; omission counts describe only excluded candidates in this display window. Fleet uses its existing 16-entry projection. See the [exact stdio schema and examples](../../../../docs/rpc.md#subagent-observability-desktop--headless-clients) and [JSON Schema](../../../../docs/rpc-subagent.schema.json).

package/dist/extensions/pi-subagents/src/extension/index.ts

@@ -30,6 +30,7 @@ import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { getAgentDir } from "../shared/utils.ts";
 import { isStaleExtensionContextError, withCachedUiContext } from "../shared/extension-context.ts";
 import { currentCompletionOwnerId } from "../shared/completion-owner.ts";
+import { ensureOwnerRecord } from "../shared/owner-record.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
@@ -59,7 +60,9 @@ import { registerHerdrStatusBridge, type HerdrStatusRun } from "../integrations/
 import { hasLiveSubagentWork, registerPiWebSessionLiveness } from "../integrations/pi-web-session-liveness.ts";
 import { createRetainedNestedRouteTracker } from "../runs/background/retained-nested-route-tracker.ts";
 import { listHerdrProjectPaneRoots, restoreHerdrProjectPaneSnapshots } from "../inspectors/herdr/project-panes.ts";
-import { registerSubagentRpcBridge } from "./rpc.ts";
+import { buildFleetStatus, registerSubagentRpcBridge } from "./rpc.ts";
+import { registerSubagentObservability } from "./observability.ts";
+import { findUndeliveredResults, registerReleaseReadiness } from "./release-readiness.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { resolveWaitToolConfig } from "../runs/background/subagent-wait.ts";
 import { registerWaitTool } from "../runs/background/wait-tool.ts";
@@ -425,6 +428,13 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	DIRS.results = ensureAccessibleDir(DIRS.results);
 	DIRS.async = ensureAccessibleDir(DIRS.async);
+	DIRS.owners = ensureAccessibleDir(DIRS.owners);
+	try {
+		// Idempotent per process: an extension reload shares the owner id and finds its record already on disk.
+		ensureOwnerRecord({ ownersDir: DIRS.owners });
+	} catch (error) {
+		console.error("Failed to write the subagent completion-owner record; finished background results cannot be taken over after this process exits:", error);
+	}
 	cleanupOldChainDirs();
 
 	const config = loadConfig();
@@ -743,6 +753,44 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	const observationFleetKeys = { sessionId: null as string | null, next: 0, keys: new Map<string, string>() };
+	const observability = registerSubagentObservability({
+		events: pi.events, state,
+		getHostSessionId: () => state.supervisorOwnerSessionId ?? null,
+		getWaitingChildren: () => supervisorChannel.pending.values(),
+		getFleet: () => buildFleetStatus(state, observationFleetKeys, state.currentSessionId),
+	});
+
+	// Release readiness (release:readiness:v1): keyed on the host session identity, like observability above.
+	const releaseReadiness = registerReleaseReadiness({
+		events: pi.events,
+		getHostSessionId: () => state.supervisorOwnerSessionId ?? null,
+		subagents: {
+			state,
+			hasPendingDelivery: () => completionNotifier.hasPendingDelivery(),
+			hasDeliveryDemand: hasResultDeliveryDemand,
+			listUndeliveredResults: () => findUndeliveredResults({
+				resultsDir: DIRS.results,
+				sessionIds: [state.currentSessionId, ...resultDeliveryOwnership.claimedSessionIds()],
+				owns: (sessionId, completionOwnerId) => resultDeliveryOwnership.owns(sessionId, completionOwnerId),
+				canTakeOver: (sessionId, completionOwnerId, runKey) => resultDeliveryOwnership.canTakeOver(sessionId, completionOwnerId, runKey),
+			}),
+		},
+		scheduler: {
+			armedSchedules: () => scheduledRunManager.armedSchedules(),
+			observedCompletionRunIds: () => scheduledRunManager.observedCompletionRunIds(),
+		},
+		// Kill switch (stop_all_background): same session gate as the readiness contributors above.
+		stopAll: {
+			subagents: {
+				state,
+				observedCompletionRunIds: () => scheduledRunManager.observedCompletionRunIds(),
+				stopRun: (target) => rpcBridge.stopRun(target),
+			},
+			scheduler: { disarmSessionSchedules: () => scheduledRunManager.disarmSessionOnlySchedules() },
+		},
+	});
+
 	const rpcBridge = registerSubagentRpcBridge({
 		events: pi.events,
 		getContext: () => state.lastUiContext,
@@ -894,6 +942,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		pi.events.on(SUBAGENT_STEERING_NOTICE_EVENT, steeringNoticeHandler),
 		herdrStatusBridge.dispose,
 		rpcBridge.dispose,
+		observability.dispose,
+		releaseReadiness.dispose,
 	];
 
 	pi.on("tool_result", (event, ctx) => {

package/dist/extensions/pi-subagents/src/extension/observability.ts

@@ -0,0 +1,164 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  SUBAGENT_OBSERVE_EVENT, SUBAGENT_RPC_MAX_BYTES,
+  type SubagentObserveRequest, type SubagentRpcNode, type SubagentRpcProjection, type SubagentRpcLifecycle,
+} from "@selesai/code";
+import type { SubagentState } from "../shared/types.ts";
+import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text.ts";
+
+interface Events { on(name: string, handler: (payload: unknown) => void): (() => void) | void }
+interface WaitingChild { runId: string; childIndex: number; expectsReply: boolean }
+const statuses = new Set(["queued", "pending", "running", "complete", "completed", "failed", "partial", "paused", "stopped", "rejected", "detached"]);
+const record = (v: unknown): v is Record<string, unknown> => Boolean(v && typeof v === "object" && !Array.isArray(v));
+const count = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+function text(v: unknown, max: number): string | undefined {
+  if (typeof v !== "string") return undefined;
+  return truncateDisplayText(sanitizeDisplayText(v.slice(0, 4096)), max) || undefined;
+}
+function identity(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 && v.length <= 128 && !/[\\/\r\n]/.test(v) ? v : undefined;
+}
+function tokens(v: unknown) {
+  if (!record(v) || !count(v.input) || !count(v.output) || !count(v.total)) return undefined;
+  return { input: v.input, output: v.output, total: v.total,
+    ...(count(v.window) ? { window: v.window } : {}), ...(count(v.windowPeak) ? { windowPeak: v.windowPeak } : {}) };
+}
+
+/** Simple adapter over runtime-owned memory. No artifact reads, executors, or new run state. */
+export function registerSubagentObservability(options: {
+  events: Events;
+  state: SubagentState;
+  getHostSessionId(): string | null;
+  getWaitingChildren(): Iterable<WaitingChild>;
+  getFleet(): SubagentRpcProjection["fleet"];
+}): { dispose(): void } {
+  const salt = randomUUID();
+  const key = (internal: string) => `node-${createHash("sha256").update(salt).update(internal).digest("hex").slice(0, 24)}`;
+  const subscribers = new Set<(projection: SubagentRpcProjection | null) => void>();
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let disposed = false;
+  let boundSession: string | null = null;
+  const snapshot = (): SubagentRpcProjection => {
+    if (disposed) throw new Error("Subagent observation source disposed");
+    const { state } = options;
+    const sessionId = state.currentSessionId;
+    const waiting = new Set([...options.getWaitingChildren()].filter(r => r.expectsReply).map(r => `${r.runId}:${r.childIndex}`));
+    let nodes = 0;
+    const representedNativeIds = new Set<string>();
+    const omitted = { runs: 0, children: 0 };
+    const project = (raw: unknown, internal: string, depth: number, runId?: string, childIndex?: number, retained = false): SubagentRpcNode | undefined => {
+      if (!record(raw) || !statuses.has((raw.status ?? raw.state) as string) || nodes >= 64 || depth > 4) return undefined;
+      nodes++;
+      const node: SubagentRpcNode = { key: key(internal), status: (raw.status ?? raw.state) as SubagentRpcLifecycle, children: [], omittedChildren: 0 };
+      const nativeRunId = identity(raw.runId ?? raw.asyncId ?? raw.id);
+      if (nativeRunId) { node.runId = nativeRunId; representedNativeIds.add(nativeRunId); }
+      const workflowId = identity(raw.parentWorkflowRunId ?? (raw.mode === "workflow" ? nativeRunId : undefined));
+      if (workflowId) node.workflowId = workflowId;
+      const agent = text(raw.agent ?? raw.currentAgent, 96);
+      if (agent) node.agent = agent;
+      if (waiting.has(`${runId ?? nativeRunId}:${childIndex ?? raw.index ?? raw.currentIndex ?? 0}`)) node.activity = "waiting_supervisor";
+      else if ((raw.activityState ?? raw.currentActivityState) === "needs_attention") node.activity = "needs_attention";
+      for (const [field, value] of [["startedAt", raw.startedAt], ["updatedAt", raw.updatedAt ?? raw.lastUpdate], ["endedAt", raw.endedAt]] as const) if (count(value)) node[field] = value;
+      const progress = text(Array.isArray(raw.recentOutput) ? raw.recentOutput.slice(-1)[0] : raw.description, 256);
+      if (progress) node.progress = progress;
+      const currentTool = text(raw.currentTool, 96);
+      if (currentTool) node.currentTool = currentTool;
+      const usage = tokens(raw.totalTokens ?? raw.tokens) ?? (count(raw.inputTokens) && count(raw.outputTokens) && count(raw.tokens)
+        ? tokens({ input: raw.inputTokens, output: raw.outputTokens, total: raw.tokens, window: raw.window, windowPeak: raw.windowPeak }) : undefined);
+      if (usage) node.tokens = usage;
+      const error = text(raw.error, 256);
+      if (error) node.error = error;
+      const reason = text(raw.reason ?? raw.detachedReason, 128);
+      if (reason) node.reason = reason;
+      const execution = raw.execution;
+      if (record(execution) && statuses.has(execution.status as string)) node.outcome = {
+        status: execution.status as SubagentRpcLifecycle,
+        ...(typeof execution.success === "boolean" ? { success: execution.success } : {}),
+        ...(typeof execution.exitCode === "number" && Number.isSafeInteger(execution.exitCode) ? { exitCode: execution.exitCode } : {}),
+      };
+      const proof = raw.processTerminal;
+      if (record(proof) && ["pending", "observed", "unknown", "not-started"].includes(proof.state as string)) node.processTerminal = {
+        state: proof.state as NonNullable<SubagentRpcNode["processTerminal"]>["state"],
+        ...(count(proof.observedAt) ? { observedAt: proof.observedAt } : {}),
+        ...(text(proof.reason, 128) ? { reason: text(proof.reason, 128) } : {}),
+      };
+      const lists = [raw.activeChildren instanceof Map ? [...raw.activeChildren.values()].map(c => ({ ...c, status: "running" })) : [],
+        Array.isArray(raw.steps) ? raw.steps : [], Array.isArray(raw.children) ? raw.children : [], Array.isArray(raw.nestedChildren) ? raw.nestedChildren : []];
+      let offset = 0;
+      for (const [listIndex, list] of lists.entries()) for (const child of list) {
+        const index = record(child) && count(child.index) ? child.index : offset;
+        const childId = record(child) ? identity(child.runId ?? child.id ?? child.workflowKey) : undefined;
+        if (retained && childId && representedNativeIds.has(childId)) { offset++; continue; }
+        const childNode = node.children.length < 16 ? project(child, `${internal}:${listIndex}:${childId ?? index}`, depth + 1, nativeRunId ?? runId, index, retained) : undefined;
+        offset++;
+        if (childNode) node.children.push(childNode);
+        else { node.omittedChildren++; omitted.children++; }
+      }
+      return node;
+    };
+    const runs: SubagentRpcNode[] = [];
+    const add = (raw: unknown, internal: string, retained = false) => {
+      const node = runs.length < 32 ? project(raw, internal, 0, undefined, undefined, retained) : undefined;
+      if (node) runs.push(node); else omitted.runs++;
+    };
+    if (sessionId) {
+      for (const control of state.foregroundControls.values()) if (control.sessionId === sessionId) add({ ...control, status: "running" }, `foreground:${control.runId}`);
+      for (const run of state.foregroundRuns?.values() ?? []) if (run.sessionId === sessionId && !state.foregroundControls.has(run.runId)) {
+        // Retained per-child lifecycle is authoritative; the run has no aggregate verdict.
+        for (const child of run.children) add({ ...child, runId: run.runId }, `foreground:${run.runId}:${child.index}`);
+      }
+      const seen = new Set<string>();
+      for (const jobs of [state.asyncJobs, state.fleetJobs]) for (const job of jobs?.values() ?? []) {
+        if (job.sessionId !== sessionId || seen.has(job.asyncId)) continue;
+        seen.add(job.asyncId);
+        add(job, `async:${job.asyncId}`);
+      }
+    }
+    for (const [rootRunId, cached] of state.retainedForegroundNestedChildren ?? []) {
+      if (cached.sessionId !== sessionId || !state.retainedForegroundNestedRoutes?.has(rootRunId)) continue;
+      for (const descendant of cached.children) {
+        if (representedNativeIds.has(descendant.id)) continue;
+        // These are actual nested runs; the settled foreground root has no invented aggregate state.
+        add({ ...descendant, parentWorkflowRunId: cached.workflowId }, `retained:${descendant.id}`, true);
+      }
+    }
+    const projection = { fleet: options.getFleet(), runs, omitted };
+    while (Buffer.byteLength(JSON.stringify(projection), "utf8") > SUBAGENT_RPC_MAX_BYTES - 1024 && runs.length) {
+      const removed = runs.pop()!;
+      const removeOmissions = (n: SubagentRpcNode) => { omitted.children -= n.omittedChildren; n.children.forEach(removeOmissions); };
+      removeOmissions(removed);
+      omitted.runs++;
+    }
+    return projection;
+  };
+  let previous = "";
+  const unsubscribe = options.events.on(SUBAGENT_OBSERVE_EVENT, raw => {
+    const request = raw as SubagentObserveRequest;
+    if (disposed || request?.version !== 1 || request.sessionId !== options.getHostSessionId() || typeof request.accept !== "function") return;
+    boundSession = request.sessionId;
+    request.accept({ snapshot, subscribe(listener) {
+      subscribers.add(listener);
+      if (!timer) {
+        previous = JSON.stringify(snapshot());
+        timer = setInterval(() => {
+          if (options.getHostSessionId() !== boundSession) return;
+          const projection = snapshot();
+          const current = JSON.stringify(projection);
+          if (current === previous) return;
+          previous = current;
+          for (const subscriber of subscribers) subscriber(projection);
+        }, 250);
+        timer.unref?.();
+      }
+      return () => { subscribers.delete(listener); if (!subscribers.size && timer) { clearInterval(timer); timer = undefined; } };
+    } });
+  });
+  return { dispose() {
+    if (disposed) return;
+    disposed = true;
+    if (typeof unsubscribe === "function") unsubscribe();
+    if (timer) clearInterval(timer);
+    for (const subscriber of subscribers) subscriber(null);
+    subscribers.clear();
+  } };
+}