pi-radar 0.3.0 → 0.4.0

package/extension/radar-client.ts

@@ -4,7 +4,6 @@ import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 import type {
 	DaemonPingSerialize,
-	LaunchIdentityMarkerSerialize,
 	FactsSnapshotDeserialize,
 	HandoffInboxSerialize,
 	HandoffReceiptSerialize,
@@ -114,6 +113,10 @@ export type RadarLocation = {
 	pane?: string;
 };
 
+export type RadarPresenceReport = import("./generated-contracts.ts").PresenceReportDeserialize;
+export type RadarPresenceAnswer = import("./generated-contracts.ts").PresenceAnswerSerialize;
+export type RadarPresenceRelease = import("./generated-contracts.ts").PresenceReleaseDeserialize;
+
 export type RadarProcessClaim = {
 	boot_id: string;
 	pid: number;
@@ -204,7 +207,6 @@ export type RadarWriterBinding = {
  */
 export type RadarContextValue = {
 	session: string | null;
-	launch_identity?: LaunchIdentityMarkerSerialize;
 };
 
 /**
@@ -286,7 +288,7 @@ export type RadarEffectOutcome = "completed" | "refused" | "unknown";
 /**
  * One durable spawn edge as the daemon publishes it (`spawn.get`).
  *
- * `bound.agent_id` is the exact registry identity the child obtained with the
+ * `bound.registration_id` is the exact registry identity the child obtained with the
  * launch's private token, which is the only thing that says *this* child belongs
  * to *this* spawn: a label, a pane or a session UUID would each be a guess.
  */
@@ -296,7 +298,7 @@ export type RadarSpawnEdge = {
 	created: RadarEffectOutcome;
 	launched: RadarEffectOutcome;
 	location?: RadarLocation;
-	bound?: { source: string; incarnation: string; agent_id?: string };
+	bound?: { source: string; incarnation: string; registration_id?: string };
 	exit_observation?: RadarSpawnExitObservation;
 };
 
@@ -307,7 +309,6 @@ export type RadarSpawnEdge = {
  * no exit was observed.
  */
 export type RadarSpawnExitObservation = SpawnExitObservationSerialize;
-export type RadarLaunchIdentityMarker = LaunchIdentityMarkerSerialize;
 
 /** Durable Radar-owned metadata accepted with a managed launch intent. */
 export type RadarManagedLaunchMetadata = ManagedLaunchMetadataDeserialize;
@@ -502,6 +503,43 @@ export function isUuid(value: unknown): value is string {
 	return typeof value === "string" && UUID.test(value);
 }
 
+function decodePresenceAnswer(value: unknown): RadarResult<RadarPresenceAnswer> {
+	const registrationId = recordAt(value, "registration_id");
+	const claimId = recordAt(value, "claim_id");
+	const standing = recordAt(value, "standing");
+	const subjectId = recordAt(value, "subject_id");
+	if (
+		!isUuid(registrationId) ||
+		!isUuid(claimId) ||
+		!["pending", "granted", "duplicate", "released"].includes(String(standing)) ||
+		(subjectId !== undefined && !isUuid(subjectId)) ||
+		(standing === "granted" && !isUuid(subjectId))
+	)
+		return protocol("presence reply carries no valid claim standing");
+	return { ok: true, value: value as RadarPresenceAnswer };
+}
+
+/**
+ * How Radar stands on a publisher's current session: adopted as a managed Pi
+ * session, rejected as a duplicate, still pending evidence/recovery, or not managed (yet).
+ */
+export type RadarManagement =
+	| { state: "managed"; subject_id: string }
+	| { state: "duplicate" }
+	| { state: "pending" }
+	| { state: "unmanaged" };
+
+function managementAt(value: unknown): RadarManagement | undefined {
+	const field = recordAt(value, "management");
+	const state = stringAt(field, "state");
+	if (state === "managed") {
+		const subjectId = stringAt(field, "subject_id");
+		return subjectId === undefined ? undefined : { state, subject_id: subjectId };
+	}
+	if (state === "duplicate" || state === "pending" || state === "unmanaged") return { state };
+	return undefined;
+}
+
 function stringAt(value: unknown, field: string): string | undefined {
 	if (typeof value !== "object" || value === null) return undefined;
 	const found = (value as Record<string, unknown>)[field];
@@ -529,7 +567,7 @@ function handoffAt(value: unknown): HandoffSerialize | undefined {
 		? (value as Record<string, unknown>).correlation_id
 		: undefined;
 	if (
-		version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "agent_id")) ||
+		version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "registration_id")) ||
 		!isUuid(stringAt(sender, "session_id")) || !isUuid(stringAt(sender, "subject_id")) ||
 		!isUuid(stringAt(sender, "execution_id")) || !Number.isSafeInteger(senderGeneration) ||
 		(senderGeneration ?? 0) < 1 || !isUuid(target) || summary === undefined || content === undefined ||
@@ -548,7 +586,7 @@ function handoffReceiptAt(value: unknown): HandoffReceiptSerialize | undefined {
 	const generation = numberAt(recipient, "execution_generation");
 	const received = numberAt(value, "received_at_unix_ms");
 	if (
-		version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "agent_id")) ||
+		version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "registration_id")) ||
 		!isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) ||
 		!isUuid(stringAt(recipient, "execution_id")) || !Number.isSafeInteger(generation) ||
 		(generation ?? 0) < 1 || received === undefined || !Number.isSafeInteger(received) || received < 0
@@ -764,7 +802,7 @@ function locationAt(value: unknown): RadarLocation | undefined {
 }
 
 /**
- * One durable edge, decoded strictly. The bound child's `agent_id` is kept only
+ * 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.
  */
@@ -784,7 +822,7 @@ function spawnEdge(value: unknown): RadarResult<RadarSpawnEdge> {
 	const bound = recordAt(value, "bound");
 	const source = stringAt(bound, "source");
 	const incarnation = stringAt(bound, "incarnation");
-	const agentId = stringAt(bound, "agent_id");
+	const agentId = stringAt(bound, "registration_id");
 	const exit = exitAt(recordAt(value, "exit_observation"));
 	return {
 		ok: true,
@@ -799,7 +837,7 @@ function spawnEdge(value: unknown): RadarResult<RadarSpawnEdge> {
 						bound: {
 							source,
 							incarnation,
-							...(isUuid(agentId) ? { agent_id: agentId } : {}),
+							...(isUuid(agentId) ? { registration_id: agentId } : {}),
 						},
 					}
 				: {}),
@@ -1001,15 +1039,15 @@ export type RadarClient = {
 	ping(): Promise<RadarResult<RadarHandshake>>;
 	register(
 		registration: RadarRegistration,
-	): Promise<RadarResult<{ agent_id: string }>>;
+	): Promise<RadarResult<{ registration_id: string }>>;
 	acquire(request: {
-		agent_id: string;
+		registration_id: string;
 		channel: RadarChannel;
 		publisher: RadarPublisherIdentity;
 		replace?: { generation: number; handle: string };
 	}): Promise<RadarResult<RadarWriterBinding>>;
 	publish(request: {
-		agent_id: string;
+		registration_id: string;
 		channel: RadarChannel;
 		writer_handle: string;
 		sequence: number;
@@ -1017,8 +1055,10 @@ export type RadarClient = {
 		observed_at?: string;
 		snapshot: RadarChannelSnapshot;
 	}): Promise<RadarResult<{ sequence: number }>>;
+	presence(request: RadarPresenceReport): Promise<RadarResult<RadarPresenceAnswer>>;
+	releasePresence(request: RadarPresenceRelease): Promise<RadarResult<RadarPresenceAnswer>>;
 	context(request: {
-		agent_id: string;
+		registration_id: string;
 		publisher: RadarPublisherIdentity;
 		writer_handle?: string;
 		replace?: { generation: number; handle: string };
@@ -1026,9 +1066,9 @@ export type RadarClient = {
 		lease_ms?: number;
 		observed_at?: string;
 		context: RadarContextValue;
-	}): Promise<RadarResult<{ writer: RadarWriterBinding; warning?: string }>>;
+	}): Promise<RadarResult<{ writer: RadarWriterBinding; warning?: string; management?: RadarManagement }>>;
 	retire(request: {
-		agent_id: string;
+		registration_id: string;
 		channel: RadarChannel;
 		writer_handle: string;
 	}): Promise<RadarResult<void>>;
@@ -1061,15 +1101,15 @@ export type RadarClient = {
 	}): Promise<RadarResult<RadarSpawnEdge>>;
 	spawnGet(request_id: string): Promise<RadarResult<RadarSpawnTopology>>;
 	/** The registered child's process verdict, read from its immutable claim. */
-	agentGet(agent_id: string): Promise<RadarResult<RadarAgentProcess>>;
+	agentGet(registration_id: string): Promise<RadarResult<RadarAgentProcess>>;
 	observe(): Promise<RadarResult<RadarInventory>>;
 	/** Read the durable event journal after `after`, waiting at most `wait_ms`. */
 	communicationPublish(request: HandoffPublishParamsDeserialize & {
 		request_id: string;
 	}): Promise<RadarResult<{ handoff: HandoffSerialize; created: boolean }>>;
-	communicationInbox(request: { agent_id: string }): Promise<RadarResult<HandoffInboxSerialize>>;
-	communicationGet(request: { agent_id: string; handoff_id: string }): Promise<RadarResult<{ handoff: HandoffSerialize; receipt: HandoffReceiptSerialize | null }>>;
-	communicationAck(request: { agent_id: string; handoff_id: string }): Promise<RadarResult<{ receipt: HandoffReceiptSerialize; created: boolean }>>;
+	communicationInbox(request: { registration_id: string }): Promise<RadarResult<HandoffInboxSerialize>>;
+	communicationGet(request: { registration_id: string; handoff_id: string }): Promise<RadarResult<{ handoff: HandoffSerialize; receipt: HandoffReceiptSerialize | null }>>;
+	communicationAck(request: { registration_id: string; handoff_id: string }): Promise<RadarResult<{ receipt: HandoffReceiptSerialize; created: boolean }>>;
 	events(request: {
 		after: number;
 		epoch?: string;
@@ -1468,6 +1508,24 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 	return {
 		socketPath,
 		ping,
+		async presence(request) {
+			return withRegistry(async () => {
+				const answer = await call("agent.presence", { ...request });
+				if (!answer.ok) return answer;
+				return decodePresenceAnswer(answer.value);
+			});
+		},
+		async releasePresence(request) {
+			return withRegistry(async () => {
+				const answer = await call("agent.release", { ...request });
+				if (!answer.ok) return answer;
+				const decoded = decodePresenceAnswer(answer.value);
+				if (!decoded.ok) return decoded;
+				return decoded.value.standing === "released"
+					? decoded
+					: protocol("release reply did not confirm the claim release");
+			});
+		},
 		async register(registration) {
 			return withRegistry(async () => {
 				const answer = await call("agent.register", {
@@ -1487,15 +1545,15 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				});
 				if (answer.ok === false) return answer;
 				const record = (answer.value as { registration?: unknown }).registration;
-				const agentId = stringAt(record, "agent_id");
-				if (!isUuid(agentId)) return protocol("registration reply carries no agent_id");
-				return { ok: true, value: { agent_id: agentId } };
+				const agentId = stringAt(record, "registration_id");
+				if (!isUuid(agentId)) return protocol("registration reply carries no registration_id");
+				return { ok: true, value: { registration_id: agentId } };
 			});
 		},
 		async acquire(request) {
 			return withRegistryChannel(request.channel, async () => {
 				const answer = await call("agent.acquire", {
-					agent_id: request.agent_id,
+					registration_id: request.registration_id,
 					channel: request.channel,
 					publisher: request.publisher,
 					...(request.replace !== undefined ? { replace: request.replace } : {}),
@@ -1524,7 +1582,7 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 			}
 			return withRegistryChannel(request.channel, async () => {
 				const answer = await call("agent.publish", {
-					agent_id: request.agent_id,
+					registration_id: request.registration_id,
 					channel: request.channel,
 					writer_handle: request.writer_handle,
 					sequence: request.sequence,
@@ -1543,7 +1601,7 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 		async context(request) {
 			return withRegistry(async () => {
 				const answer = await call("agent.context", {
-					agent_id: request.agent_id,
+					registration_id: request.registration_id,
 					publisher: request.publisher,
 					...(request.writer_handle !== undefined
 						? { writer_handle: request.writer_handle }
@@ -1563,9 +1621,14 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				if (writer === undefined)
 					return protocol("context reply carries no writer binding");
 				const warning = stringAt(answer.value, "warning");
+				const management = managementAt(answer.value);
 				return {
 					ok: true,
-					value: { writer, ...(warning !== undefined ? { warning } : {}) },
+					value: {
+						writer,
+						...(warning !== undefined ? { warning } : {}),
+						...(management !== undefined ? { management } : {}),
+					},
 				};
 			});
 		},
@@ -1658,7 +1721,7 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 					message: "agent.get requires a canonical agent UUID",
 				};
 			return withRegistry(async () => {
-				const answer = await call("agent.get", { agent_id: agentId });
+				const answer = await call("agent.get", { registration_id: agentId });
 				if (answer.ok === false) return answer;
 				return agentProcessAt(recordAt(answer.value, "agent"));
 			});
@@ -1724,7 +1787,7 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 		async communicationPublish(request) {
 			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
 				const answer = await call("communication.publish", {
-					sender_agent_id: request.sender_agent_id,
+					sender_registration_id: request.sender_registration_id,
 					recipient_subject_id: request.recipient_subject_id,
 					...(request.correlation_id !== undefined ? { correlation_id: request.correlation_id } : {}),
 					summary: request.summary,

package/extension/radar-communication.ts

@@ -31,7 +31,7 @@ export function createRadarHandoffPort(
 		const subject = await publication.subject();
 		return subject === undefined
 			? { ok: false, code: "absent", message: "this process has no current Radar registration" }
-			: { ok: true, value: subject.agent_id };
+			: { ok: true, value: subject.registration_id };
 	}
 
 	return {
@@ -43,24 +43,24 @@ export function createRadarHandoffPort(
 				return { ok: false, code: "absent", message: "this managed execution has no Radar parent subject" };
 			return client.communicationPublish({
 				...request,
-				sender_agent_id: identity.value,
+				sender_registration_id: identity.value,
 				recipient_subject_id: parent,
 			});
 		},
 		async inbox() {
 			const identity = await agentId();
 			if (identity.ok === false) return identity;
-			return client.communicationInbox({ agent_id: identity.value });
+			return client.communicationInbox({ registration_id: identity.value });
 		},
 		async get(handoff_id) {
 			const identity = await agentId();
 			if (identity.ok === false) return identity;
-			return client.communicationGet({ agent_id: identity.value, handoff_id });
+			return client.communicationGet({ registration_id: identity.value, handoff_id });
 		},
 		async ack(handoff_id) {
 			const identity = await agentId();
 			if (identity.ok === false) return identity;
-			return client.communicationAck({ agent_id: identity.value, handoff_id });
+			return client.communicationAck({ registration_id: identity.value, handoff_id });
 		},
 	};
 }

package/extension/radar-execution.ts

@@ -3,7 +3,6 @@ import {
 	isUuid,
 	type RadarScheduler,
 	type RadarSnapshot,
-	type RadarLaunchIdentityMarker,
 } from "./radar-client.ts";
 import type { RadarLocationResolution } from "./radar-location.ts";
 import type { RadarFactsSnapshot } from "./radar-client.ts";
@@ -20,11 +19,6 @@ import {
 	type RadarPublication,
 	type RadarChannelWriter,
 } from "./radar-publication.ts";
-import {
-	activeRadarLaunchMarker,
-	persistRadarLaunchMarker,
-	radarLaunchMarkerFromEnvironment,
-} from "./radar-session-marker.ts";
 
 /**
  * The minimal Pi surface this adapter uses. It is declared structurally so the
@@ -32,7 +26,6 @@ import {
  * be lifted into its own extension without touching this module.
  */
 export type RadarExecutionEventApi = {
-	appendEntry?: (customType: string, data?: unknown) => void;
 	on(name: string, handler: (event: any, context: any) => unknown): unknown;
 	events?: {
 		on(name: string, handler: (event: any) => unknown): unknown;
@@ -70,10 +63,8 @@ export type RadarExecutionOptions = {
 	 * where no such event exists.
 	 */
 	questionnaireEvent?: string;
-	/** Best-effort diagnostic for durable session marker failures. */
+	/** Best-effort diagnostic for context publication failures. */
 	diagnostic?: (message: string) => void;
-	/** Injectable only for tests; production reads the daemon-issued process env. */
-	markerEnvironment?: Record<string, string | undefined>;
 };
 
 export type RadarExecutionAdapter = {
@@ -138,10 +129,13 @@ function unavailablePublication(): RadarPublication {
 	return {
 		execution: writer,
 		facts: { ...writer, update: () => undefined },
-		context: {
-			update: () => undefined,
+		presence: {
+			report: () => undefined,
 			stop: () => undefined,
 			reopen: () => undefined,
+			management: () => undefined,
+			ensure: async () => undefined,
+			release: async () => undefined,
 			diagnostic: () => "Radar private storage is unavailable",
 		},
 		assignment: () => writer,
@@ -269,14 +263,11 @@ export function createRadarExecutionAdapter(
 	 * canonical UUID is left unreported: absent context is unknown, and publishing
 	 * the explicit null would claim there is no session at all.
 	 */
-	function reportSession(
-		context: any,
-		launchIdentity?: RadarLaunchIdentityMarker,
-	): void {
+	function reportSession(context: any): void {
 		const session = context?.sessionManager?.getSessionId?.();
 		if (!isUuid(session)) return;
 		try {
-			publication.context.update(session, launchIdentity);
+			publication.presence.report(session);
 		} catch {
 			// Optional publication must not interfere with Pi's lifecycle handler.
 		}
@@ -360,49 +351,10 @@ export function createRadarExecutionAdapter(
 		);
 
 	on("session_start", (_event, context) => {
-		const sessionHost = {
-			appendEntry: pi.appendEntry
-				? (customType: string, data?: unknown) => pi.appendEntry?.(customType, data)
-				: undefined,
-			sessionManager: context?.sessionManager,
-		};
-		let launchIdentity: RadarLaunchIdentityMarker | undefined;
-		try {
-			const result = persistRadarLaunchMarker(
-				sessionHost,
-				options.markerEnvironment,
-			);
-			if (result === "written" || result === "unchanged") {
-				const expected = radarLaunchMarkerFromEnvironment(options.markerEnvironment);
-				const activeMarker = activeRadarLaunchMarker(sessionHost);
-				if (
-					expected &&
-					activeMarker.status === "valid" &&
-					JSON.stringify(activeMarker.marker) === JSON.stringify(expected)
-				) {
-					launchIdentity = activeMarker.marker;
-				} else {
-					options.diagnostic?.("Radar launch marker was not visible on the active Pi session branch");
-				}
-			} else if (result === "unsupported") {
-				options.diagnostic?.("Pi host does not support Radar launch identity session entries");
-			} else if (
-				options.markerEnvironment &&
-				[
-					"PI_RADAR_MANAGED_SUBJECT_ID",
-					"PI_RADAR_MANAGED_LAUNCH_ID",
-					"PI_RADAR_MANAGED_EXECUTION_GENERATION",
-				].some((key) => options.markerEnvironment?.[key] !== undefined)
-			) {
-				options.diagnostic?.("incomplete or invalid Radar launch identity environment");
-			}
-		} catch (error) {
-			options.diagnostic?.(`could not persist Radar launch marker: ${String(error)}`);
-		}
 		rootSession = true;
 		// The session comes first: re-arming the publication must renew the session
 		// this process is in now, never the one a previous session left behind.
-		reportSession(context, launchIdentity);
+		reportSession(context);
 		// Facts follow the root flag, so they are published only after it is set.
 		publishFacts(context);
 		// A process can replace or resume its session without a new process, so the
@@ -450,12 +402,13 @@ export function createRadarExecutionAdapter(
 		emit();
 	});
 
-	on("session_shutdown", () => {
+	on("session_shutdown", async () => {
 		// A session can end or be replaced without ending this process, and Pi keeps
 		// the same extension instance across that: the listeners stay registered so
 		// the next session_start re-arms the same process publication. Only the
 		// timers and this session's facts are released.
 		suspend();
+		await publication.presence.release();
 	});
 
 	function suspend(): void {

package/extension/radar-launch.ts

@@ -46,7 +46,7 @@ export type LaunchMailbox<State extends LaunchState> = {
  *    the child's exact command into it, and still reports that pane in its own
  *    inventory;
  * 2. a child registered with the launch's private token, so the edge names the
- *    exact `agent_id` that child obtained — never a label, pane or session;
+ *    exact `registration_id` that child obtained — never a label, pane or session;
  * 3. that child wrote a fresh startup acknowledgment for this launch generation
  *    after Herdsman startup finished, naming the pane the daemon created as its
  *    own location.
@@ -66,7 +66,7 @@ export type LaunchMailbox<State extends LaunchState> = {
 
 /** The exact managed parent this launch may use, and nothing inferred about it. */
 export type RadarLaunchParent = {
-	agent_id: string;
+	registration_id: string;
 	/** Stable subject from this process's current Radar registration. */
 	subject_id: string;
 	location?: RadarLocation;
@@ -109,12 +109,12 @@ export type RadarWorkerLaunch = {
 	 * because a binding that was not persisted is one no later reader can hold the
 	 * child by.
 	 */
-	onBound?: (bound: { agent_id: string; pane_id: string }) => void;
+	onBound?: (bound: { registration_id: string; pane_id: string }) => void;
 };
 
 export type RadarWorkerLaunched<State = unknown> = {
 	request_id: string;
-	agent_id: string;
+	registration_id: string;
 	pane_id: string;
 	/**
 	 * The process the daemon bound this launch's edge to, taken from that same
@@ -143,7 +143,7 @@ export type RadarLaunchOutcome<State = unknown> =
  */
 export type RadarChildEvidence = {
 	request_id: string;
-	agent_id: string;
+	registration_id: string;
 	source: string;
 	incarnation: string;
 	pane_id: string;
@@ -192,12 +192,12 @@ export async function observeRadarChild(
 	provenance: {
 		request_id: string;
 		pane_id: string | undefined;
-		agent_id: string | undefined;
+		registration_id: string | undefined;
 		/** The session this launch's mailbox records for the child. */
 		session_id: string | undefined;
 	},
 ): Promise<RadarChildObservation> {
-	if (provenance.agent_id === undefined)
+	if (provenance.registration_id === undefined)
 		return unknownChild("not bound to a child by this launch");
 	// A launch that recorded no pane has nothing to compare the daemon's read
 	// against: the child's own claim about where it runs is not where the launch
@@ -211,11 +211,11 @@ export async function observeRadarChild(
 		);
 	const topology = read.value;
 	const edge = topology.edge;
-	if (edge.bound === undefined || edge.bound.agent_id === undefined)
+	if (edge.bound === undefined || edge.bound.registration_id === undefined)
 		return unknownChild("not bound to a child by the daemon");
-	if (edge.bound.agent_id !== provenance.agent_id)
+	if (edge.bound.registration_id !== provenance.registration_id)
 		return unknownChild(
-			`bound to another subject (${edge.bound.agent_id}), not to ${provenance.agent_id}`,
+			`bound to another subject (${edge.bound.registration_id}), not to ${provenance.registration_id}`,
 		);
 	if (edge.location?.pane === undefined)
 		return unknownChild("recorded without a pane");
@@ -241,7 +241,7 @@ export async function observeRadarChild(
 	// The edge says where the child was bound, not that its process still runs.
 	// The registry's verdict on the bound subject, and the location it registered
 	// with, are what prove the child live.
-	const reply = await client.agentGet(edge.bound.agent_id);
+	const reply = await client.agentGet(edge.bound.registration_id);
 	if (reply.ok === false)
 		return unknownChild(
 			`process verdict not readable (${reply.code}: ${reply.message})`,
@@ -271,7 +271,7 @@ export async function observeRadarChild(
 		kind: "live",
 		evidence: {
 			request_id: provenance.request_id,
-			agent_id: edge.bound.agent_id,
+			registration_id: edge.bound.registration_id,
 			source: edge.bound.source,
 			incarnation: edge.bound.incarnation,
 			pane_id: edge.location.pane,
@@ -393,7 +393,7 @@ export async function launchRadarWorker<State extends LaunchState>(
 	const deadline = Date.now() + options.timeoutMs;
 	const remaining = (): number => Math.max(0, deadline - Date.now());
 	const pane = launch.parent.location?.pane;
-	if (!isUuid(launch.parent.agent_id))
+	if (!isUuid(launch.parent.registration_id))
 		return refusedLaunch(
 			"the launch has no exact parent registration to spawn under",
 		);
@@ -411,7 +411,7 @@ export async function launchRadarWorker<State extends LaunchState>(
 
 	const spawned = await client.spawn({
 		request_id: launch.request_id,
-		parent: launch.parent.agent_id,
+		parent: launch.parent.registration_id,
 		parent_session_id: launch.parent_session_id,
 		executable: launch.executable,
 		managed: { parent_subject_id: launch.parent.subject_id },
@@ -437,13 +437,13 @@ export async function launchRadarWorker<State extends LaunchState>(
 		...(signal !== undefined ? { signal } : {}),
 	});
 	if (bound.kind !== "bound") return bound;
-	const agentId = bound.agent_id;
+	const agentId = bound.registration_id;
 	// The binding is recorded before the readiness wait, not after it: the child
 	// may never acknowledge, and the subject and pane the daemon named are still
 	// what a reload has to prove this child by.
 	if (launch.onBound !== undefined) {
 		try {
-			launch.onBound({ agent_id: agentId, pane_id: bound.pane_id });
+			launch.onBound({ registration_id: agentId, pane_id: bound.pane_id });
 		} catch (error) {
 			return unresolvedLaunch(
 				launch.request_id,
@@ -475,7 +475,7 @@ export async function launchRadarWorker<State extends LaunchState>(
 			kind: "ready",
 			value: {
 				request_id: launch.request_id,
-				agent_id: agentId,
+				registration_id: agentId,
 				pane_id: bound.pane_id,
 				bound_process: {
 					source: bound.source,
@@ -498,7 +498,7 @@ export async function launchRadarWorker<State extends LaunchState>(
 type BoundChild =
 	| {
 			kind: "bound";
-			agent_id: string;
+			registration_id: string;
 			pane_id: string;
 			source: string;
 			incarnation: string;
@@ -509,7 +509,7 @@ type BoundChild =
  * Poll the edge this request id authored until a child presents its token.
  *
  * The daemon binds the edge once, to the exact registration the token produced,
- * so `bound.agent_id` is the child identity. A refusal or an unknown launch
+ * so `bound.registration_id` is the child identity. A refusal or an unknown launch
  * effect ends the wait at once: neither becomes a child by waiting longer. An
  * edge whose recorded pane the daemon no longer reports ends it too: waiting
  * cannot create the pane a launch claims, and a location read afterwards would
@@ -559,7 +559,7 @@ async function waitForChild(
 					requestId,
 					"the daemon observed the launched child's process exit",
 				);
-			const agentId = edge.bound?.agent_id;
+			const agentId = edge.bound?.registration_id;
 			if (agentId !== undefined && isUuid(agentId)) {
 				// A child the daemon bound without the process it registered as is a
 				// child no assignment can be addressed to, and an unaddressed Radar
@@ -579,7 +579,7 @@ async function waitForChild(
 					);
 				return {
 					kind: "bound",
-					agent_id: agentId,
+					registration_id: agentId,
 					pane_id: pane,
 					source,
 					incarnation,