pi-radar 0.9.0 → 0.11.0

package/extension/radar-children.ts

@@ -1,176 +1,81 @@
+import { randomUUID } from "node:crypto";
 import type { RadarClient, RadarChannelSnapshot, RadarResult } from "./radar-client.ts";
-import type { SpawnListPageSerializePublicSpawnTopology as ListedEdge } from "./generated-contracts.ts";
-import { inspectRadarChild, type RadarInspection } from "./radar-inspection.ts";
-import { observeRadarChild, type RadarChildObservation } from "./radar-launch.ts";
+import type { SubjectGetResult, SubjectChildrenParams } from "./generated-contracts.ts";
+import type { RadarInspection } from "./radar-inspection.ts";
+import { waitForChild, launchFailure, type RadarLaunchOutcome } from "./radar-launch.ts";
 import type { RadarPublication } from "./radar-publication.ts";
 
-const PAGE = 100;
-const MAX_PAGES = 20;
-
-/** One child of the caller, named by the agent that survives its restarts. */
-export type RadarChild = {
-	subject_id: string;
-	/** The launch that last bound this child. */
-	request_id: string;
-	pane_id?: string;
-	state: "unbound" | "bound" | "unresolved";
-	exited: boolean;
-};
-
-/** The assignment a child is held to: published again when its process is replaced. */
+/** An agent, including its retained identity when no process is attached. */
+export type RadarChild = SubjectGetResult["subject"];
 export type RadarChildAssignment = {
 	update(snapshot: RadarChannelSnapshot): void;
 	retire(): void;
 };
-
+export type RadarChildProgram = {
+	executable: string;
+	argv: string[];
+	cwd?: string;
+	env?: Record<string, string>;
+};
+export type RadarChildObservation =
+	| { kind: "live"; subject: RadarChild }
+	| { kind: "gone"; subject: RadarChild }
+	| { kind: "unknown"; diagnostic: string };
 export type RadarChildren = {
-	list(): Promise<RadarResult<RadarChild[]>>;
+	list(selection?: SubjectChildrenParams["selection"]): Promise<RadarResult<RadarChild[]>>;
+	restart(subject: string, program: RadarChildProgram, options?: { pollMs?: number; signal?: AbortSignal }): Promise<RadarLaunchOutcome>;
 	assignment(subject: string, owner: string): RadarChildAssignment;
 	retire(subject: string): void;
-	observe(
-		subject: string,
-		session_id: string | undefined,
-	): Promise<RadarChildObservation>;
-	inspect(subject: string, session_id?: string): Promise<RadarInspection>;
+	observe(subject: string): Promise<RadarChildObservation>;
+	inspect(subject: string): Promise<RadarInspection>;
 };
 
-type Resolved = { child: RadarChild; registration_id: string };
-
-/**
- * The caller's children, addressed by subject. A subject gains an edge per launch,
- * so the newest bound edge is the current process; its registration is read per
- * call and never remembered, because a remembered registration is the stale key
- * this surface exists to hide. An edge bound without a subject is not addressable.
- */
+/** All child lifecycle resolution and assignment ownership belong to Radar. */
 export function createRadarChildren(
-	client: Pick<RadarClient, "spawnList" | "spawnGet" | "agentGet" | "output" | "processInfo">,
-	publication: Pick<RadarPublication, "assignment" | "retireAssignment">,
+	client: Pick<RadarClient, "subjectChildren" | "childGet" | "childInspect" | "spawnGet" | "restart">,
+	publication: Pick<RadarPublication, "assignment" | "retireAssignment" | "subject">,
 ): RadarChildren {
-	const held = new Map<
-		string,
-		{ writer: RadarChildAssignment; published?: string; publish?: (target: Resolved) => void }
-	>();
-
-	async function resolveAll(): Promise<RadarResult<Map<string, Resolved & { at: number }>>> {
-		const newest = new Map<string, Resolved & { at: number }>();
-		let after: string | undefined;
-		for (let page = 0; page < MAX_PAGES; page++) {
-			const read = await client.spawnList({ ...(after !== undefined ? { after } : {}), limit: PAGE });
-			if (read.ok === false) return read;
-			for (const edge of read.value.spawns as ListedEdge[]) {
-				const bound = edge.bound;
-				if (!bound?.subject_id || !bound.registration_id || edge.launched !== "completed") continue;
-				const at = Date.parse(bound.bound_at);
-				if (Number.isNaN(at)) continue;
-				const current = newest.get(bound.subject_id);
-				if (current !== undefined && current.at >= at) continue;
-				newest.set(bound.subject_id, {
-					at,
-					registration_id: bound.registration_id,
-					child: {
-						subject_id: bound.subject_id,
-						request_id: edge.request_id,
-						...(edge.location?.pane ? { pane_id: edge.location.pane } : {}),
-						state: edge.state,
-						exited: edge.exit_observation != null && edge.exit_observation.state !== "unknown",
-					},
-				});
-			}
-			if (!read.value.next) return { ok: true, value: newest };
-			after = read.value.next;
-		}
-		return { ok: false, code: "protocol", message: "the caller's launches exceed the readable pages" };
-	}
-
-	async function resolve(subject: string): Promise<Resolved | undefined> {
-		const all = await resolveAll();
-		return all.ok ? all.value.get(subject) : undefined;
-	}
-
-	async function resolveAndFollow(subject: string): Promise<Resolved | undefined> {
-		const all = await resolveAll();
-		if (!all.ok) return undefined;
-		follow(all.value);
-		return all.value.get(subject);
-	}
-
-	/**
-	 * A child replaced under its subject has a new process with no assignment. Each
-	 * read the caller already makes finds the new registration and moves the held
-	 * assignment onto it, so no caller has to notice a replacement.
-	 */
-	function follow(all: Map<string, Resolved>): void {
-		for (const [subject, entry] of held) {
-			const target = all.get(subject);
-			if (target !== undefined && entry.published !== target.registration_id)
-				entry.publish?.(target);
-		}
-	}
-
 	return {
-		async list() {
-			const all = await resolveAll();
-			if (!all.ok) return all;
-			follow(all.value);
-			return { ok: true, value: [...all.value.values()].map((entry) => entry.child) };
-		},
-		assignment(subject, owner) {
-			const existing = held.get(subject);
-			if (existing !== undefined) return existing.writer;
-			let latest: RadarChannelSnapshot | undefined;
-			const entry: {
-				writer: RadarChildAssignment;
-				published?: string;
-				publish?: (target: Resolved) => void;
-			} = { writer: undefined as unknown as RadarChildAssignment };
-			const send = (target: Resolved): void => {
-				if (latest === undefined) return;
-				if (entry.published !== undefined && entry.published !== target.registration_id)
-					publication.retireAssignment(entry.published);
-				entry.published = target.registration_id;
-				publication.assignment(target.registration_id, owner).update(latest);
-			};
-			entry.publish = send;
-			entry.writer = {
-				update(snapshot) {
-					latest = snapshot;
-					void resolve(subject).then((target) => {
-						if (target !== undefined) send(target);
-					});
-				},
-				retire() {
-					latest = undefined;
-					if (entry.published !== undefined) publication.retireAssignment(entry.published);
-					entry.published = undefined;
-				},
-			};
-			held.set(subject, entry);
-			return entry.writer;
+		async list(selection) {
+			const children: RadarChild[] = [];
+			let after: string | undefined;
+			do {
+				const page = await client.subjectChildren({ selection, after, limit: 100 });
+				if (!page.ok) return page;
+				children.push(...page.value.subjects);
+				if (page.value.next === after)
+					return { ok: false, code: "protocol", message: "child page did not advance" };
+				after = page.value.next ?? undefined;
+			} while (after !== undefined);
+			return { ok: true, value: children };
 		},
-		retire(subject) {
-			held.get(subject)?.writer.retire();
-			held.delete(subject);
-		},
-		async observe(subject, session_id) {
-			const target = await resolveAndFollow(subject);
-			if (target === undefined)
-				return { kind: "unknown", diagnostic: "the daemon records no bound launch for this child" };
-			return observeRadarChild(client as RadarClient, {
-				request_id: target.child.request_id,
-				pane_id: target.child.pane_id,
-				registration_id: target.registration_id,
-				session_id,
+		async restart(subject, program, options) {
+			const parent = await publication.subject();
+			if (parent?.subject_id === undefined)
+				return { kind: "failed", message: "this process has no granted subject" };
+			const request_id = randomUUID();
+			const requested = await client.restart({ request_id, parent: parent.registration_id, subject_id: subject, ...program });
+			if (!requested.ok) return launchFailure(requested, request_id);
+			const bound = await waitForChild(client, requested.value.launch_request_id, {
+				pollMs: options?.pollMs ?? 250,
+				...(options?.signal !== undefined ? { signal: options.signal } : {}),
 			});
+			if (bound.kind !== "bound") return bound;
+			return { kind: "ready", value: { request_id: requested.value.launch_request_id, subject_id: bound.subject_id, pane_id: bound.pane_id } };
 		},
-		async inspect(subject, session_id) {
-			const target = await resolveAndFollow(subject);
-			if (target?.child.pane_id === undefined)
-				throw new Error("Inspection target is not a bound child with a pane");
-			return inspectRadarChild(client as RadarClient, {
-				agentId: target.registration_id,
-				paneId: target.child.pane_id,
-				...(session_id !== undefined ? { session: session_id } : {}),
-			});
+		assignment: (subject, owner) => publication.assignment(subject, owner),
+		retire: (subject) => publication.retireAssignment(subject),
+		async observe(subject) {
+			const read = await client.childGet(subject);
+			if (!read.ok) return { kind: "unknown", diagnostic: `${read.code}: ${read.message}` };
+			if (read.value.state === "live") return { kind: "live", subject: read.value };
+			if (read.value.state === "detached") return { kind: "gone", subject: read.value };
+			return { kind: "unknown", diagnostic: `child attachment is ${read.value.state}` };
+		},
+		async inspect(subject) {
+			const read = await client.childInspect(subject);
+			if (!read.ok) throw new Error(`Child inspection unavailable (${read.code}: ${read.message})`);
+			return read.value;
 		},
 	};
 }

package/extension/radar-client.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import type { RadarInspection } from "./radar-inspection.ts";
 import { lstatSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
@@ -13,6 +14,10 @@ import type {
 	SpawnExitObservationSerialize,
 	SpawnListParamsDeserialize,
 	SpawnListPageSerialize,
+	SubjectChildGetParams,
+	SubjectChildrenParams,
+	SubjectGetResult,
+	SubjectListResult,
 } from "./generated-contracts.ts";
 
 /**
@@ -38,12 +43,11 @@ export const RADAR_PROTOCOL_VERSION = 2;
  * parent continue or restart its own child by subject.
  * Earlier daemons expose different identity fields; require a coordinated update.
  */
-export const RADAR_MINIMUM_REVISION = 7;
+export const RADAR_MINIMUM_REVISION = 9;
 /** Public daemon contracts this client may preflight. */
 export const RADAR_REGISTRY_CONTRACT = "registry.v1";
 export const RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 export const RADAR_SPAWN_CONTRACT = "spawn.v1";
-export const RADAR_SPAWN_LIST_CONTRACT = "spawn.list.v1";
 export const RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
 export const RADAR_LIFECYCLE_RESTART_CONTRACT = "lifecycle.restart.v1";
 export const RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
@@ -309,6 +313,9 @@ export type RadarSpawnEdge = {
 	location?: RadarLocation;
 	bound?: { source: string; incarnation: string; registration_id?: string; subject_id?: string };
 	exit_observation?: RadarSpawnExitObservation;
+	/** Set when the daemon withdrew the launch before its process presented. */
+	withdrawn?: { at: string; reason: string };
+	granted_at?: string;
 };
 
 /**
@@ -808,8 +815,7 @@ function locationAt(value: unknown): RadarLocation | undefined {
 
 /**
  * One durable edge, decoded strictly. The bound child's `registration_id` is kept only
- * when it is a canonical UUID: a legacy binding has none, and an unreadable one
- * is not an identity to correlate with.
+ * when it is a canonical UUID: an unreadable one is not an identity to correlate with.
  */
 function spawnEdge(value: unknown): RadarResult<RadarSpawnEdge> {
 	const requestId = stringAt(value, "request_id");
@@ -830,6 +836,9 @@ function spawnEdge(value: unknown): RadarResult<RadarSpawnEdge> {
 	const agentId = stringAt(bound, "registration_id");
 	const subjectId = stringAt(bound, "subject_id");
 	const exit = exitAt(recordAt(value, "exit_observation"));
+	const withdrawnRecord = recordAt(value, "withdrawn");
+	const withdrawnAt = stringAt(withdrawnRecord, "at");
+	const withdrawnReason = stringAt(withdrawnRecord, "reason");
 	return {
 		ok: true,
 		value: {
@@ -849,6 +858,10 @@ function spawnEdge(value: unknown): RadarResult<RadarSpawnEdge> {
 					}
 				: {}),
 			...(exit !== undefined ? { exit_observation: exit } : {}),
+			...(stringAt(value, "granted_at") !== undefined ? { granted_at: stringAt(value, "granted_at") } : {}),
+			...(withdrawnAt !== undefined && withdrawnReason !== undefined
+				? { withdrawn: { at: withdrawnAt, reason: withdrawnReason } }
+				: {}),
 		},
 	};
 }
@@ -867,6 +880,16 @@ const PROCESS_VERDICTS: readonly RadarProcessVerdict[] = [
 	"unavailable",
 ];
 
+function subjectAt(value: unknown): RadarResult<SubjectGetResult["subject"]> {
+	const subjectId = recordAt(value, "subject_id");
+	const session = recordAt(value, "session_id");
+	const state = recordAt(value, "state");
+	if (!isUuid(subjectId) || (session != null && !isUuid(session)) ||
+		!["starting", "live", "detached", "unknown"].includes(String(state)))
+		return protocol("subject read carries no valid identity or attachment state");
+	return { ok: true, value: value as SubjectGetResult["subject"] };
+}
+
 function agentProcessAt(agent: unknown): RadarResult<RadarAgentProcess> {
 	const process = recordAt(agent, "process");
 	const claimed = recordAt(process, "claimed");
@@ -1051,13 +1074,15 @@ export type RadarClient = {
 		registration: RadarRegistration,
 	): Promise<RadarResult<{ registration_id: string }>>;
 	acquire(request: {
-		registration_id: string;
+		registration_id?: string;
+		subject_id?: string;
 		channel: RadarChannel;
 		publisher: RadarPublisherIdentity;
 		replace?: { generation: number; handle: string };
 	}): Promise<RadarResult<RadarWriterBinding>>;
 	publish(request: {
-		registration_id: string;
+		registration_id?: string;
+		subject_id?: string;
 		channel: RadarChannel;
 		writer_handle: string;
 		sequence: number;
@@ -1078,7 +1103,8 @@ export type RadarClient = {
 		context: RadarContextValue;
 	}): Promise<RadarResult<{ writer: RadarWriterBinding; warning?: string; management?: RadarManagement }>>;
 	retire(request: {
-		registration_id: string;
+		registration_id?: string;
+		subject_id?: string;
 		channel: RadarChannel;
 		writer_handle: string;
 	}): Promise<RadarResult<void>>;
@@ -1124,10 +1150,13 @@ export type RadarClient = {
 		argv: string[];
 		cwd?: string;
 		env?: Record<string, string>;
-	}): Promise<RadarResult<{ request_id: string }>>;
+	}): Promise<RadarResult<{ request_id: string; launch_request_id: string }>>;
 	/** List launches owned by this client's registered process. */
 	spawnList(request: Pick<SpawnListParamsDeserialize, "after" | "limit">): Promise<RadarResult<SpawnListPageSerialize>>;
 	spawnGet(request_id: string): Promise<RadarResult<RadarSpawnTopology>>;
+	subjectChildren(request?: Omit<SubjectChildrenParams, "registration_id">): Promise<RadarResult<SubjectListResult>>;
+	childGet(subject_id: string): Promise<RadarResult<SubjectGetResult["subject"]>>;
+	childInspect(subject_id: string): Promise<RadarResult<RadarInspection>>;
 	/** The registered child's process verdict, read from its immutable claim. */
 	agentGet(registration_id: string): Promise<RadarResult<RadarAgentProcess>>;
 	observe(): Promise<RadarResult<RadarInventory>>;
@@ -1541,7 +1570,11 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 			return withRegistry(async () => {
 				const answer = await call("agent.presence", { ...request });
 				if (!answer.ok) return answer;
-				return decodePresenceAnswer(answer.value);
+				const decoded = decodePresenceAnswer(answer.value);
+				// Presence names the caller's own registration, which is the
+				// authority every subject-addressed child call is checked against.
+				if (decoded.ok) processRegistrationId = decoded.value.registration_id;
+				return decoded;
 			});
 		},
 		async releasePresence(request) {
@@ -1582,9 +1615,13 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 		},
 		async acquire(request) {
 			return withRegistryChannel(request.channel, async () => {
-				const answer = await call("agent.acquire", {
-					registration_id: request.registration_id,
-					channel: request.channel,
+				const assignment = request.channel === "assignment";
+				if (assignment && processRegistrationId === undefined)
+					return { ok: false, code: "refused", message: "assignment requires a granted parent" };
+				if (assignment && request.subject_id === undefined)
+					return { ok: false, code: "bad_params", message: "an assignment names a child subject" };
+				const answer = await call(assignment ? "subject.assignment.acquire" : "agent.acquire", {
+					...(assignment ? { registration_id: processRegistrationId, subject_id: request.subject_id } : { registration_id: request.registration_id, channel: request.channel }),
 					publisher: request.publisher,
 					...(request.replace !== undefined ? { replace: request.replace } : {}),
 				});
@@ -1611,15 +1648,21 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				}
 			}
 			return withRegistryChannel(request.channel, async () => {
-				const answer = await call("agent.publish", {
-					registration_id: request.registration_id,
-					channel: request.channel,
+				const update = {
 					writer_handle: request.writer_handle,
 					sequence: request.sequence,
 					...(request.lease_ms !== undefined ? { lease_ms: request.lease_ms } : {}),
 					...(request.observed_at !== undefined ? { observed_at: request.observed_at } : {}),
 					snapshot,
-				});
+				};
+				const assignment = request.channel === "assignment";
+				if (assignment && processRegistrationId === undefined)
+					return { ok: false, code: "refused", message: "assignment requires a granted parent" };
+				if (assignment && request.subject_id === undefined)
+					return { ok: false, code: "bad_params", message: "an assignment names a child subject" };
+				const answer = await call(assignment ? "subject.assignment.publish" : "agent.publish", assignment
+					? { registration_id: processRegistrationId, subject_id: request.subject_id, update }
+					: { registration_id: request.registration_id, channel: request.channel, ...update });
 				if (answer.ok === false) return answer;
 				const channel = (answer.value as { channel?: unknown }).channel;
 				const writer = (channel as { writer?: unknown } | undefined)?.writer;
@@ -1664,7 +1707,17 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 		},
 		async retire(request) {
 			return withRegistryChannel(request.channel, async () => {
-				const answer = await call("agent.retire", request);
+				const assignment = request.channel === "assignment";
+				if (assignment && processRegistrationId === undefined)
+					return { ok: false, code: "refused", message: "assignment requires a granted parent" };
+				if (assignment && request.subject_id === undefined)
+					return { ok: false, code: "bad_params", message: "an assignment names a child subject" };
+				const answer = await call(assignment ? "subject.assignment.retire" : "agent.retire", {
+					...(assignment
+						? { registration_id: processRegistrationId, subject_id: request.subject_id }
+						: { registration_id: request.registration_id, channel: request.channel }),
+					writer_handle: request.writer_handle,
+				});
 				return answer.ok === true ? { ok: true, value: undefined } : answer;
 			});
 		},
@@ -1757,14 +1810,72 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 					request.request_id,
 				);
 				if (answer.ok === false) return answer;
-				return focusOutcome(recordAt(answer.value, "request"), request.request_id);
+				const settled = focusOutcome(recordAt(answer.value, "request"), request.request_id);
+				if (settled.ok === false) return settled;
+				const launch = recordAt(recordAt(answer.value, "request"), "launch_request_id");
+				if (!isUuid(launch)) return protocol("lifecycle.restart reply names no launch");
+				return { ok: true, value: { ...settled.value, launch_request_id: launch } };
+			});
+		},
+		async subjectChildren(request = {}) {
+			const registrationId = processRegistrationId;
+			if (registrationId === undefined)
+				return { ok: false, code: "refused", message: "this process has no Radar registration" };
+			return withRegistry(async () => {
+				const params: SubjectChildrenParams = { ...request, registration_id: registrationId };
+				const answer = await call("subject.children", { ...params });
+				if (!answer.ok) return answer;
+				const subjects = recordAt(answer.value, "subjects");
+				const next = recordAt(answer.value, "next");
+				if (!Array.isArray(subjects) || (next != null && !isUuid(next)))
+					return protocol("subject.children reply carries no valid page");
+				for (const subject of subjects) {
+					const decoded = subjectAt(subject);
+					if (!decoded.ok) return decoded;
+				}
+				return { ok: true, value: answer.value as SubjectListResult };
+			});
+		},
+		async childGet(subject_id) {
+			const registrationId = processRegistrationId;
+			if (registrationId === undefined)
+				return { ok: false, code: "refused", message: "this process has no Radar registration" };
+			if (!isUuid(subject_id))
+				return { ok: false, code: "bad_params", message: "child requires a subject UUID" };
+			return withRegistry(async () => {
+				const params: SubjectChildGetParams = { registration_id: registrationId, subject_id };
+				const answer = await call("subject.child.get", { ...params });
+				return answer.ok ? subjectAt(recordAt(answer.value, "subject")) : answer;
+			});
+		},
+		async childInspect(subject_id) {
+			const registration_id = processRegistrationId;
+			if (registration_id === undefined)
+				return { ok: false, code: "refused", message: "this process has no Radar registration" };
+			return withRegistry(async () => {
+				const answer = await call("subject.child.inspect", { registration_id, subject_id });
+				if (!answer.ok) return answer;
+				const subject = subjectAt(recordAt(answer.value, "subject"));
+				if (!subject.ok) return subject;
+				const output = recordAt(answer.value, "output");
+				const text = stringAt(output, "text");
+				if (text === undefined || typeof recordAt(output, "truncated") !== "boolean")
+					return protocol("child inspection has no output evidence");
+				const foreground = recordAt(answer.value, "foreground");
+				const activity = subject.value.execution?.snapshot?.snapshot;
+				return { ok: true, value: {
+					capturedAt: Date.now(), recentOutputTruncated: recordAt(output, "truncated") as boolean,
+					...(text ? { recentOutput: text } : {}),
+					...(foreground ? { foreground: foreground as RadarForeground } : {}),
+					...(activity && "activity" in activity ? { activity: activity.activity } : {}),
+				} };
 			});
 		},
 		async spawnList(request) {
 			const registrationId = processRegistrationId;
 			if (registrationId === undefined)
 				return { ok: false, code: "refused", message: "spawn.list requires this client's process registration" };
-			return withContract(RADAR_SPAWN_LIST_CONTRACT, async () => {
+			return withRegistry(async () => {
 				const params: SpawnListParamsDeserialize = {
 					registration_id: registrationId,
 					...(request.after !== undefined ? { after: request.after } : {}),

package/extension/radar-inspection.ts

@@ -1,85 +1,10 @@
-import {
-	type RadarAgentProcess,
-	type RadarClient,
-	type RadarForeground,
-} from "./radar-client.ts";
-
-// The caps the removed Herdr inspection applied; evidence is returned, never
-// the pane's full scrollback.
-const INSPECTION_LINES = 80;
-const INSPECTION_OUTPUT_BYTES = 16 * 1024;
+import type { RadarForeground } from "./radar-client.ts";
 
+/** Bounded evidence captured and identity-checked by Radar for one child subject. */
 export type RadarInspection = {
 	capturedAt: number;
 	recentOutputTruncated: boolean;
 	recentOutput?: string;
 	foreground?: RadarForeground;
-	/** The child's published activity from the proof read; unknown when absent. */
 	activity?: string;
 };
-
-/**
- * The registration's own read when the registered child `agentId` still runs on
- * `paneId` (and, when `session` is given, still publishes that session): a
- * `verified` verdict. Absent, mismatched, unavailable and unreadable are not
- * proof.
- */
-export async function provedRead(
-	client: Pick<RadarClient, "agentGet">,
-	target: { agentId: string; paneId: string; session?: string },
-): Promise<RadarAgentProcess | undefined> {
-	const read = await client.agentGet(target.agentId);
-	return read.ok === true &&
-		read.value.verification === "verified" &&
-		read.value.location?.pane === target.paneId &&
-		(target.session === undefined ||
-			read.value.contextSession === target.session)
-		? read.value
-		: undefined;
-}
-
-/**
- * Reads a managed child's recent output and foreground process, once the
- * registered child is proved on its pane before and after the read.
- */
-export async function inspectRadarChild(
-	client: RadarClient,
-	target: { agentId: string; paneId: string; session?: string },
-): Promise<RadarInspection> {
-	const before = await provedRead(client, target);
-	if (before === undefined)
-		throw new Error("Inspection target identity did not match");
-	const output = await client.output({
-		pane_id: target.paneId,
-		source: "recent_unwrapped",
-		lines: INSPECTION_LINES,
-	});
-	if (output.ok === false)
-		throw new Error(
-			`Inspection output unavailable (${output.code}: ${output.message})`,
-		);
-	const foreground = await client.processInfo({ pane_id: target.paneId });
-	const after = await provedRead(client, target);
-	if (after === undefined)
-		throw new Error("Inspection target changed during capture");
-	const lines = output.value.text.trim().split(/\r?\n/).slice(-INSPECTION_LINES);
-	const bounded = utf8Tail(lines.join("\n"), INSPECTION_OUTPUT_BYTES);
-	return Object.freeze({
-		capturedAt: Date.now(),
-		recentOutputTruncated: output.value.truncated || bounded.truncated,
-		...(bounded.text ? { recentOutput: bounded.text } : {}),
-		...(foreground.ok === true ? { foreground: foreground.value } : {}),
-		...(after.activity !== undefined ? { activity: after.activity } : {}),
-	});
-}
-
-function utf8Tail(
-	value: string,
-	maxBytes: number,
-): { text: string; truncated: boolean } {
-	const bytes = Buffer.from(value);
-	if (bytes.length <= maxBytes) return { text: value, truncated: false };
-	let start = bytes.length - maxBytes;
-	while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start++;
-	return { text: bytes.subarray(start).toString(), truncated: true };
-}