pi-radar 0.1.0 → 0.2.0

package/dist/index.js

@@ -38,7 +38,7 @@ import { lstatSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 var RADAR_PROTOCOL_VERSION = 2;
-var RADAR_MINIMUM_REVISION = 1;
+var RADAR_MINIMUM_REVISION = 3;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";
@@ -258,6 +258,11 @@ function unresolvedOperation(requestId, detail) {
   };
 }
 var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
+var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
+  "PI_RADAR_MANAGED_SUBJECT_ID",
+  "PI_RADAR_MANAGED_LAUNCH_ID",
+  "PI_RADAR_MANAGED_EXECUTION_GENERATION"
+]);
 function unresolvedSpawn(requestId, detail) {
   return {
     ok: false,
@@ -402,9 +407,23 @@ function spawnRequestShape(request) {
   for (const [name, value] of env) {
     if (name === RADAR_SPAWN_TOKEN_ENV)
       return `spawn env cannot set the reserved ${RADAR_SPAWN_TOKEN_ENV}`;
+    if (RADAR_MANAGED_IDENTITY_ENV.has(name))
+      return `spawn env cannot set Radar-issued identity variable ${name}`;
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || new RegExp("\\p{Cc}", "u").test(value))
       return `spawn env contains an invalid name or value: ${name}`;
   }
+  if (request.managed !== void 0) {
+    if (typeof request.managed !== "object" || request.managed === null)
+      return "managed launch metadata must be an object";
+    for (const [name, value] of Object.entries(request.managed)) {
+      if (!["owner", "run", "label", "role", "parent_subject_id"].includes(name))
+        return `unknown managed launch metadata field: ${name}`;
+      if (value != null && (typeof value !== "string" || value.trim() === "" || new TextEncoder().encode(value).length > 256 || new RegExp("\\p{Cc}", "u").test(value)))
+        return `managed launch ${name} must be non-empty, control-free, and at most 256 UTF-8 bytes`;
+    }
+    if (request.managed.parent_subject_id != null && !isUuid(request.managed.parent_subject_id))
+      return "managed parent_subject_id must be a canonical UUID";
+  }
   return void 0;
 }
 function focusOutcome(record, requestId) {
@@ -815,7 +834,8 @@ function createRadarClient(options = {}) {
                 executable: request.executable,
                 argv: request.argv,
                 ...request.cwd !== void 0 ? { cwd: request.cwd } : {},
-                ...carriesContext && request.env !== void 0 ? { env: request.env } : {}
+                ...carriesContext && request.env !== void 0 ? { env: request.env } : {},
+                ...request.managed !== void 0 ? { managed: request.managed } : {}
               },
               requester
             },
@@ -1173,6 +1193,77 @@ import {
   writeSync
 } from "node:fs";
 import { dirname as dirname2, join as join2, parse, resolve, sep } from "node:path";
+
+// extension/radar-session-marker.ts
+var RADAR_LAUNCH_MARKER_TYPE = "pi-radar.launch-identity";
+var RADAR_LAUNCH_MARKER_VERSION = 1;
+var RADAR_MAX_EXECUTION_GENERATION = 4294967295;
+var RADAR_MANAGED_SUBJECT_ENV = "PI_RADAR_MANAGED_SUBJECT_ID";
+var RADAR_MANAGED_LAUNCH_ENV = "PI_RADAR_MANAGED_LAUNCH_ID";
+var RADAR_MANAGED_GENERATION_ENV = "PI_RADAR_MANAGED_EXECUTION_GENERATION";
+var UUID2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+function decodeRadarLaunchMarker(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const record = value;
+  if (Object.keys(record).sort().join(",") !== "execution_generation,launch_id,subject_id,version") {
+    return void 0;
+  }
+  if (record.version !== RADAR_LAUNCH_MARKER_VERSION || typeof record.subject_id !== "string" || !UUID2.test(record.subject_id) || typeof record.launch_id !== "string" || !UUID2.test(record.launch_id) || !Number.isSafeInteger(record.execution_generation) || record.execution_generation < 1 || record.execution_generation > RADAR_MAX_EXECUTION_GENERATION) {
+    return void 0;
+  }
+  return {
+    version: RADAR_LAUNCH_MARKER_VERSION,
+    subject_id: record.subject_id,
+    launch_id: record.launch_id,
+    execution_generation: record.execution_generation
+  };
+}
+function appendRadarLaunchMarker(appendEntry, marker) {
+  const validated = decodeRadarLaunchMarker(marker);
+  if (!validated) throw new Error("invalid Radar launch identity marker");
+  appendEntry(RADAR_LAUNCH_MARKER_TYPE, validated);
+}
+function latestRadarLaunchMarker(branch) {
+  let latest;
+  for (const entry of branch) {
+    if (entry.type === "custom" && entry.customType === RADAR_LAUNCH_MARKER_TYPE) {
+      latest = entry;
+    }
+  }
+  if (!latest) return { status: "absent" };
+  const marker = decodeRadarLaunchMarker(latest.data);
+  return marker ? { status: "valid", marker } : { status: "invalid" };
+}
+function radarLaunchMarkerFromEnvironment(env = process.env) {
+  const rawGeneration = env[RADAR_MANAGED_GENERATION_ENV];
+  if (env[RADAR_MANAGED_SUBJECT_ENV] === void 0 || env[RADAR_MANAGED_LAUNCH_ENV] === void 0 || rawGeneration === void 0 || !/^[1-9][0-9]*$/.test(rawGeneration)) {
+    return void 0;
+  }
+  return decodeRadarLaunchMarker({
+    version: RADAR_LAUNCH_MARKER_VERSION,
+    subject_id: env[RADAR_MANAGED_SUBJECT_ENV],
+    launch_id: env[RADAR_MANAGED_LAUNCH_ENV],
+    execution_generation: Number(rawGeneration)
+  });
+}
+function activeRadarLaunchMarker(host) {
+  if (!host.sessionManager) return { status: "absent" };
+  return latestRadarLaunchMarker(host.sessionManager.getBranch());
+}
+function persistRadarLaunchMarker(host, env = process.env) {
+  const marker = radarLaunchMarkerFromEnvironment(env);
+  if (!marker) return "absent";
+  if (!host.appendEntry || !host.sessionManager) return "unsupported";
+  const current = latestRadarLaunchMarker(host.sessionManager.getBranch());
+  if (current.status === "valid" && sameMarker(current.marker, marker)) return "unchanged";
+  appendRadarLaunchMarker(host.appendEntry, marker);
+  return "written";
+}
+function sameMarker(a, b) {
+  return a.version === b.version && a.subject_id === b.subject_id && a.launch_id === b.launch_id && a.execution_generation === b.execution_generation;
+}
+
+// extension/radar-publication.ts
 var RADAR_PUBLICATION_VERSION = 1;
 var RADAR_LEASE_MS = 3e4;
 var RADAR_HEARTBEAT_MS = 15e3;
@@ -1483,15 +1574,21 @@ function pendingAt(value, keys = PENDING_KEYS, codec = executionCodec) {
   return { sequence, snapshot, lease_ms: lease, observed_at: observed };
 }
 var CONTEXT_PENDING_KEYS = "lease_ms,observed_at,sequence,session";
+var CONTEXT_PENDING_MARKED_KEYS = "launch_identity,lease_ms,observed_at,sequence,session";
 var CONTEXT_ACCEPTED_KEYS = "lease_ms,observed_at,sent_at,sequence,session";
+var CONTEXT_ACCEPTED_MARKED_KEYS = "launch_identity,lease_ms,observed_at,sent_at,sequence,session";
 function sessionAt(value) {
   if (typeof value !== "object" || value === null) return void 0;
   const found = value.session;
   if (found === null) return null;
   return typeof found === "string" ? found : void 0;
 }
-function contextReportAt(value, keys) {
-  if (!exactKeys(value, keys)) return void 0;
+function sameLaunchIdentity(a, b) {
+  return a === b || a !== void 0 && b !== void 0 && a.version === b.version && a.subject_id === b.subject_id && a.launch_id === b.launch_id && a.execution_generation === b.execution_generation;
+}
+function contextReportAt(value, keys, markedKeys) {
+  const marked = exactKeys(value, markedKeys);
+  if (!exactKeys(value, keys) && !marked) return void 0;
   const sequence = numberAt2(value, "sequence");
   const lease = numberAt2(value, "lease_ms");
   const observed = textAt(value, "observed_at");
@@ -1499,7 +1596,15 @@ function contextReportAt(value, keys) {
   if (sequence === void 0 || sequence < 1) return void 0;
   if (lease === void 0 || observed === void 0 || session === void 0)
     return void 0;
-  return { sequence, session, lease_ms: lease, observed_at: observed };
+  const marker = marked ? decodeRadarLaunchMarker(value.launch_identity) : void 0;
+  if (marked && marker === void 0) return void 0;
+  return {
+    sequence,
+    session,
+    lease_ms: lease,
+    observed_at: observed,
+    ...marker !== void 0 ? { launch_identity: marker } : {}
+  };
 }
 function createChannelWriter(input) {
   const { store, client, scheduler, recordName, channel, publisher } = input;
@@ -1738,6 +1843,7 @@ function createContextWriter(input) {
   const { store, client, scheduler, recordName, publisher } = input;
   let record = loadRecord();
   let desired;
+  let desiredMarker;
   let running = false;
   let again = false;
   let recovering = false;
@@ -1763,9 +1869,17 @@ function createContextWriter(input) {
     const generation = numberAt2(writer, "generation");
     if (writer !== void 0 && (!exactKeys(writer, WRITER_KEYS) || !isUuid(handle) || generation === void 0))
       return blank(agentId);
-    const pending = contextReportAt(recordAt2(value, "pending"), CONTEXT_PENDING_KEYS);
+    const pending = contextReportAt(
+      recordAt2(value, "pending"),
+      CONTEXT_PENDING_KEYS,
+      CONTEXT_PENDING_MARKED_KEYS
+    );
     const acceptedValue = recordAt2(value, "accepted");
-    const accepted = contextReportAt(acceptedValue, CONTEXT_ACCEPTED_KEYS);
+    const accepted = contextReportAt(
+      acceptedValue,
+      CONTEXT_ACCEPTED_KEYS,
+      CONTEXT_ACCEPTED_MARKED_KEYS
+    );
     const sentAt = numberAt2(acceptedValue, "sent_at");
     return {
       version: RADAR_PUBLICATION_VERSION,
@@ -1825,7 +1939,10 @@ function createContextWriter(input) {
       sequence: pending.sequence,
       lease_ms: pending.lease_ms,
       observed_at: pending.observed_at,
-      context: { session: pending.session }
+      context: {
+        session: pending.session,
+        ...pending.launch_identity !== void 0 ? { launch_identity: pending.launch_identity } : {}
+      }
     });
     if (answer.ok === true) {
       recovering = false;
@@ -1856,12 +1973,13 @@ function createContextWriter(input) {
       return;
     }
   }
-  async function stage(session) {
+  async function stage(session, launchIdentity) {
     const pending = {
       sequence: record.sequence + 1,
       session,
       lease_ms: input.leaseMs,
-      observed_at: new Date(scheduler.now()).toISOString()
+      observed_at: new Date(scheduler.now()).toISOString(),
+      ...launchIdentity !== void 0 ? { launch_identity: launchIdentity } : {}
     };
     record.pending = pending;
     save();
@@ -1876,11 +1994,11 @@ function createContextWriter(input) {
     if (desired === void 0) return;
     if (!await ensureSubject()) return;
     if (fenced) return;
-    if (record.writer === void 0 || record.accepted === void 0 || record.accepted.session !== desired) {
-      await stage(desired);
+    if (record.writer === void 0 || record.accepted === void 0 || record.accepted.session !== desired || !sameLaunchIdentity(record.accepted.launch_identity, desiredMarker)) {
+      await stage(desired, desiredMarker);
       return;
     }
-    if (heartbeatDue()) await stage(record.accepted.session);
+    if (heartbeatDue()) await stage(record.accepted.session, desiredMarker);
   }
   async function drain() {
     if (running || stopped || fenced) return;
@@ -1912,9 +2030,11 @@ function createContextWriter(input) {
     void drain().catch(() => void 0);
   }
   return {
-    update(session) {
-      if (fenced || session === desired) return;
+    update(session, launchIdentity) {
+      if (fenced || session === desired && sameLaunchIdentity(desiredMarker, launchIdentity))
+        return;
       desired = session;
+      desiredMarker = launchIdentity;
       if (stopped) return;
       kick();
     },
@@ -2326,11 +2446,11 @@ function createRadarExecutionAdapter(pi, options) {
       ...lastOutcome !== void 0 ? { last_outcome: lastOutcome } : {}
     };
   }
-  function reportSession(context) {
+  function reportSession(context, launchIdentity) {
     const session = context?.sessionManager?.getSessionId?.();
     if (!isUuid(session)) return;
     try {
-      publication.context.update(session);
+      publication.context.update(session, launchIdentity);
     } catch {
     }
   }
@@ -2394,8 +2514,38 @@ function createRadarExecutionAdapter(pi, options) {
       })
     );
   on("session_start", (_event, context) => {
+    const sessionHost = {
+      appendEntry: pi.appendEntry ? (customType, data) => pi.appendEntry?.(customType, data) : void 0,
+      sessionManager: context?.sessionManager
+    };
+    let launchIdentity;
+    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] !== void 0)) {
+        options.diagnostic?.("incomplete or invalid Radar launch identity environment");
+      }
+    } catch (error) {
+      options.diagnostic?.(`could not persist Radar launch marker: ${String(error)}`);
+    }
     rootSession = true;
-    reportSession(context);
+    reportSession(context, launchIdentity);
     publishFacts(context);
     publication.reopen();
     active = context?.isIdle?.() === false;
@@ -2582,7 +2732,8 @@ async function resolveRadarProcessLocation(client, env = process.env) {
   const backend = ready.value.backend;
   if (backend === void 0 || backend === "none")
     return { state: "absent", reason: "the daemon serves no physical backend" };
-  const own = qualifiedOwnPane(env, backend, ready.value.instance);
+  const instance = ready.value.instance ?? void 0;
+  const own = qualifiedOwnPane(env, backend, instance);
   if ("absent" in own) return { state: "absent", reason: own.absent };
   if ("pending" in own) return { state: "pending", reason: own.pending };
   const paneId = own.pane;
@@ -2614,7 +2765,6 @@ async function resolveRadarProcessLocation(client, env = process.env) {
   if ("ambiguous" in containment)
     return { state: "pending", reason: containment.ambiguous };
   const row = containment.pane;
-  const instance = ready.value.instance;
   return {
     state: "resolved",
     location: {
@@ -2895,11 +3045,56 @@ async function waitForChild(client, requestId, options) {
     });
   }
 }
+
+// extension/radar-runtime.ts
+var radar_runtime_exports = {};
+__export(radar_runtime_exports, {
+  RADAR_RUNTIME_REQUEST: () => RADAR_RUNTIME_REQUEST,
+  RADAR_RUNTIME_VERSION: () => RADAR_RUNTIME_VERSION,
+  lazyRadarRuntime: () => lazyRadarRuntime,
+  provideRadarRuntime: () => provideRadarRuntime,
+  requestRadarRuntime: () => requestRadarRuntime
+});
+var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
+var RADAR_RUNTIME_VERSION = 1;
+function lazyRadarRuntime(start) {
+  let pending;
+  return {
+    version: RADAR_RUNTIME_VERSION,
+    start: () => pending ??= Promise.resolve().then(start)
+  };
+}
+function provideRadarRuntime(events, handle) {
+  return events.on(RADAR_RUNTIME_REQUEST, (value) => {
+    if (!isRuntimeRequest(value)) return;
+    value.provide(handle);
+  });
+}
+function requestRadarRuntime(events) {
+  const handles = [];
+  events.emit(RADAR_RUNTIME_REQUEST, {
+    version: RADAR_RUNTIME_VERSION,
+    provide: (candidate) => {
+      if (isRadarRuntimeHandle(candidate)) handles.push(candidate);
+    }
+  });
+  if (handles.length === 1) return { ok: true, handle: handles[0] };
+  return { ok: false, reason: handles.length === 0 ? "missing" : "duplicate" };
+}
+function isRuntimeRequest(value) {
+  return typeof value === "object" && value !== null && value.version === RADAR_RUNTIME_VERSION && typeof value.provide === "function";
+}
+function isRadarRuntimeHandle(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const handle = value;
+  return handle.version === RADAR_RUNTIME_VERSION && typeof handle.start === "function";
+}
 export {
   radar_client_exports as client,
   radar_execution_exports as execution,
   radar_inspection_exports as inspection,
   radar_launch_exports as launch,
   radar_location_exports as location,
-  radar_publication_exports as publication
+  radar_publication_exports as publication,
+  radar_runtime_exports as runtime
 };

package/extension/baseline.ts

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createRadarClient } from "./radar-client.ts";
+import {
+	createRadarExecutionAdapter,
+	type RadarExecutionEventApi,
+} from "./radar-execution.ts";
+import { resolveRadarProcessLocation } from "./radar-location.ts";
+import {
+	lazyRadarRuntime,
+	provideRadarRuntime,
+	type RadarExtensionEventBus,
+} from "./radar-runtime.ts";
+
+/** Minimal structural Pi API used by the baseline extension. */
+type PiRadarHost = RadarExecutionEventApi & {
+	events: RadarExtensionEventBus;
+};
+
+/**
+ * Register pi-radar as the one baseline registrar for this Pi process.
+ * Herdsman integrations request the same session-scoped runtime handle over
+ * `pi.events`; they add orchestration data without creating another publisher.
+ */
+export default function registerPiRadar(pi: PiRadarHost): void {
+	const client = createRadarClient();
+	const execution = createRadarExecutionAdapter(pi, {
+		client,
+		dataRoot: join(homedir(), ".pi", "agent", "pi-radar"),
+		location: () => resolveRadarProcessLocation(client),
+	});
+	const runtime = lazyRadarRuntime(async () => ({
+		publication: execution.publication,
+		execution,
+	}));
+	provideRadarRuntime(pi.events, runtime);
+}

package/extension/generated-contracts.ts

@@ -19,6 +19,27 @@ export interface TaskLaneStatus {
   available: boolean;
   error: string | null;
 }
+/**
+ * Managed owner/parent metadata accepted with a spawn intent. Domain validation
+ * and parent-binding checks remain in the daemon handler.
+ */
+export interface ManagedLaunchMetadataDeserialize {
+  label?: string | null;
+  owner?: string | null;
+  parent_subject_id?: string | null;
+  role?: string | null;
+  run?: string | null;
+}
+/**
+ * A non-secret Pi-session breadcrumb issued by Radar. This is correlation
+ * evidence only and cannot establish lifecycle authority.
+ */
+export interface LaunchIdentityMarkerSerialize {
+  execution_generation: number;
+  launch_id: string;
+  subject_id: string;
+  version: number;
+}
 /**
  * The agent's own process facts. Self-authored by any Pi session, with no owner
  * or assignment, and kept separate from execution and assignment. Every field

package/extension/radar-client.ts

@@ -4,7 +4,9 @@ import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 import type {
 	DaemonPingSerialize,
+	LaunchIdentityMarkerSerialize,
 	FactsSnapshotDeserialize,
+	ManagedLaunchMetadataDeserialize,
 	SpawnExitObservationSerialize,
 } from "./generated-contracts.ts";
 
@@ -26,7 +28,7 @@ import type {
  */
 export const RADAR_PROTOCOL_VERSION = 2;
 /** The minimum daemon wire revision this client understands. */
-export const RADAR_MINIMUM_REVISION = 1;
+export const RADAR_MINIMUM_REVISION = 3;
 /** Public daemon contracts this client may preflight. */
 export const RADAR_REGISTRY_CONTRACT = "registry.v1";
 export const RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
@@ -194,6 +196,7 @@ export type RadarWriterBinding = {
  */
 export type RadarContextValue = {
 	session: string | null;
+	launch_identity?: LaunchIdentityMarkerSerialize;
 };
 
 /**
@@ -296,6 +299,10 @@ 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;
 
 /**
  * One edge with what *that read* learned about the location it recorded.
@@ -651,6 +658,11 @@ function unresolvedOperation(requestId: string, detail: string): RadarResult<nev
 }
 
 export const RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
+const RADAR_MANAGED_IDENTITY_ENV = new Set([
+	"PI_RADAR_MANAGED_SUBJECT_ID",
+	"PI_RADAR_MANAGED_LAUNCH_ID",
+	"PI_RADAR_MANAGED_EXECUTION_GENERATION",
+]);
 
 /**
  * A spawn this process may still have caused.
@@ -857,6 +869,7 @@ function spawnRequestShape(request: {
 	argv: string[];
 	cwd?: string;
 	env?: Record<string, string>;
+	managed?: RadarManagedLaunchMetadata;
 }): string | undefined {
 	if (!isUuid(request.request_id))
 		return "spawn requires a canonical request UUID";
@@ -875,9 +888,26 @@ function spawnRequestShape(request: {
 	for (const [name, value] of env) {
 		if (name === RADAR_SPAWN_TOKEN_ENV)
 			return `spawn env cannot set the reserved ${RADAR_SPAWN_TOKEN_ENV}`;
+		if (RADAR_MANAGED_IDENTITY_ENV.has(name))
+			return `spawn env cannot set Radar-issued identity variable ${name}`;
 		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || /\p{Cc}/u.test(value))
 			return `spawn env contains an invalid name or value: ${name}`;
 	}
+	if (request.managed !== undefined) {
+		if (typeof request.managed !== "object" || request.managed === null)
+			return "managed launch metadata must be an object";
+		for (const [name, value] of Object.entries(request.managed)) {
+			if (!["owner", "run", "label", "role", "parent_subject_id"].includes(name))
+				return `unknown managed launch metadata field: ${name}`;
+			if (value != null && (typeof value !== "string" || value.trim() === "" || new TextEncoder().encode(value).length > 256 || /\p{Cc}/u.test(value)))
+				return `managed launch ${name} must be non-empty, control-free, and at most 256 UTF-8 bytes`;
+		}
+		if (
+			request.managed.parent_subject_id != null &&
+			!isUuid(request.managed.parent_subject_id)
+		)
+			return "managed parent_subject_id must be a canonical UUID";
+	}
 	return undefined;
 }
 
@@ -978,6 +1008,7 @@ export type RadarClient = {
 		argv: string[];
 		cwd?: string;
 		env?: Record<string, string>;
+		managed?: RadarManagedLaunchMetadata;
 	}): Promise<RadarResult<RadarSpawnEdge>>;
 	spawnGet(request_id: string): Promise<RadarResult<RadarSpawnTopology>>;
 	/** The registered child's process verdict, read from its immutable claim. */
@@ -1513,6 +1544,9 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 								...(carriesContext && request.env !== undefined
 									? { env: request.env }
 									: {}),
+								...(request.managed !== undefined
+									? { managed: request.managed }
+									: {}),
 							},
 							requester,
 						},

package/extension/radar-execution.ts

@@ -3,6 +3,7 @@ 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";
@@ -19,6 +20,11 @@ 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
@@ -26,6 +32,7 @@ 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;
@@ -63,6 +70,10 @@ export type RadarExecutionOptions = {
 	 * where no such event exists.
 	 */
 	questionnaireEvent?: string;
+	/** Best-effort diagnostic for durable session marker failures. */
+	diagnostic?: (message: string) => void;
+	/** Injectable only for tests; production reads the daemon-issued process env. */
+	markerEnvironment?: Record<string, string | undefined>;
 };
 
 export type RadarExecutionAdapter = {
@@ -258,11 +269,14 @@ 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): void {
+	function reportSession(
+		context: any,
+		launchIdentity?: RadarLaunchIdentityMarker,
+	): void {
 		const session = context?.sessionManager?.getSessionId?.();
 		if (!isUuid(session)) return;
 		try {
-			publication.context.update(session);
+			publication.context.update(session, launchIdentity);
 		} catch {
 			// Optional publication must not interfere with Pi's lifecycle handler.
 		}
@@ -346,10 +360,49 @@ 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);
+		reportSession(context, launchIdentity);
 		// 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

package/extension/radar-location.ts

@@ -153,7 +153,8 @@ export async function resolveRadarProcessLocation(
 	const backend = ready.value.backend;
 	if (backend === undefined || backend === "none")
 		return { state: "absent", reason: "the daemon serves no physical backend" };
-	const own = qualifiedOwnPane(env, backend, ready.value.instance);
+	const instance = ready.value.instance ?? undefined;
+	const own = qualifiedOwnPane(env, backend, instance);
 	if ("absent" in own) return { state: "absent", reason: own.absent };
 	if ("pending" in own) return { state: "pending", reason: own.pending };
 	const paneId = own.pane;
@@ -186,7 +187,6 @@ export async function resolveRadarProcessLocation(
 	if ("ambiguous" in containment)
 		return { state: "pending", reason: containment.ambiguous };
 	const row = containment.pane;
-	const instance = ready.value.instance;
 	return {
 		state: "resolved",
 		location: {