pi-radar 0.1.0 → 0.3.0

package/dist/index.js

@@ -8,6 +8,7 @@ var __export = (target, all) => {
 var radar_client_exports = {};
 __export(radar_client_exports, {
   RADAR_CALL_TIMEOUT_MS: () => RADAR_CALL_TIMEOUT_MS,
+  RADAR_COMMUNICATION_CONTRACT: () => RADAR_COMMUNICATION_CONTRACT,
   RADAR_EVENTS_CONTRACT: () => RADAR_EVENTS_CONTRACT,
   RADAR_EVENT_RETRY_MS: () => RADAR_EVENT_RETRY_MS,
   RADAR_MAX_AWAITED: () => RADAR_MAX_AWAITED,
@@ -38,13 +39,14 @@ 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";
 var RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
 var RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 var RADAR_EVENTS_CONTRACT = "events.v1";
+var RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
 var RADAR_REQUESTER = "pi-radar";
 var RADAR_MAX_LINE_BYTES = 1024 * 1024;
 var RADAR_CALL_TIMEOUT_MS = 2e3;
@@ -152,6 +154,28 @@ function numberAt(value, field) {
   const found = value[field];
   return typeof found === "number" && Number.isFinite(found) ? found : void 0;
 }
+function handoffAt(value) {
+  const version = numberAt(value, "version");
+  const id = stringAt(value, "id");
+  const sender = recordAt(value, "sender");
+  const senderGeneration = numberAt(sender, "execution_generation");
+  const target = stringAt(value, "recipient_subject_id");
+  const summary = stringAt(value, "summary");
+  const content = stringAt(value, "content");
+  const published = numberAt(value, "published_at_unix_ms");
+  const correlation = typeof value === "object" && value !== null ? value.correlation_id : void 0;
+  if (version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "agent_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 === void 0 || content === void 0 || published === void 0 || !Number.isSafeInteger(published) || published < 0 || correlation !== void 0 && correlation !== null && (typeof correlation !== "string" || correlation.length === 0 || Buffer.byteLength(correlation, "utf8") > 256 || new RegExp("\\p{Cc}", "u").test(correlation))) return void 0;
+  return value;
+}
+function handoffReceiptAt(value) {
+  const version = numberAt(value, "version");
+  const handoffId = stringAt(value, "handoff_id");
+  const recipient = recordAt(value, "recipient");
+  const generation = numberAt(recipient, "execution_generation");
+  const received = numberAt(value, "received_at_unix_ms");
+  if (version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "agent_id")) || !isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) || !isUuid(stringAt(recipient, "execution_id")) || !Number.isSafeInteger(generation) || (generation ?? 0) < 1 || received === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
+  return value;
+}
 function writerBinding(value) {
   const handle = stringAt(value, "handle");
   const source = stringAt(value, "source");
@@ -258,6 +282,12 @@ 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",
+  "PI_RADAR_MANAGED_PARENT_SUBJECT_ID"
+]);
 function unresolvedSpawn(requestId, detail) {
   return {
     ok: false,
@@ -402,9 +432,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 +859,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
             },
@@ -915,6 +960,56 @@ function createRadarClient(options = {}) {
         return protocol("spawn.close reply carries no close outcome");
       });
     },
+    async communicationPublish(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.publish", {
+          sender_agent_id: request.sender_agent_id,
+          recipient_subject_id: request.recipient_subject_id,
+          ...request.correlation_id !== void 0 ? { correlation_id: request.correlation_id } : {},
+          summary: request.summary,
+          content: request.content
+        }, request.request_id);
+        if (answer.ok === false) return answer;
+        const handoff = handoffAt(recordAt(answer.value, "handoff"));
+        const created = recordAt(answer.value, "created");
+        if (handoff === void 0 || typeof created !== "boolean")
+          return protocol("communication.publish reply carries no handoff");
+        return { ok: true, value: { handoff, created } };
+      });
+    },
+    async communicationInbox(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.inbox", request);
+        if (answer.ok === false) return answer;
+        const handoffIds = recordAt(answer.value, "handoff_ids");
+        if (!Array.isArray(handoffIds) || handoffIds.some((id) => !isUuid(id)))
+          return protocol("communication.inbox reply carries malformed handoff IDs");
+        return { ok: true, value: answer.value };
+      });
+    },
+    async communicationGet(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.get", request);
+        if (answer.ok === false) return answer;
+        const handoff = handoffAt(recordAt(answer.value, "handoff"));
+        const receiptValue = recordAt(answer.value, "receipt");
+        const receipt = receiptValue === null ? null : handoffReceiptAt(receiptValue);
+        if (handoff === void 0 || receiptValue !== null && receipt === void 0)
+          return protocol("communication.get reply carries malformed content or receipt");
+        return { ok: true, value: { handoff, receipt: receipt ?? null } };
+      });
+    },
+    async communicationAck(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.ack", request);
+        if (answer.ok === false) return answer;
+        const receipt = handoffReceiptAt(recordAt(answer.value, "receipt"));
+        const created = recordAt(answer.value, "created");
+        if (receipt === void 0 || typeof created !== "boolean")
+          return protocol("communication.ack reply carries no receipt");
+        return { ok: true, value: { receipt, created } };
+      });
+    },
     async events(request) {
       if (!Number.isSafeInteger(request.after) || request.after < 0 || !Number.isSafeInteger(request.wait_ms) || request.wait_ms < 0 || request.wait_ms > RADAR_EVENT_WAIT_MS)
         return {
@@ -1135,6 +1230,47 @@ function boundedRadarSnapshot(snapshot) {
   };
 }
 
+// extension/radar-communication.ts
+var radar_communication_exports = {};
+__export(radar_communication_exports, {
+  createRadarHandoffPort: () => createRadarHandoffPort
+});
+function createRadarHandoffPort(client, publication, parentSubjectId = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID) {
+  async function agentId() {
+    const subject = await publication.subject();
+    return subject === void 0 ? { ok: false, code: "absent", message: "this process has no current Radar registration" } : { ok: true, value: subject.agent_id };
+  }
+  return {
+    async publish(request) {
+      const identity = await agentId();
+      if (identity.ok === false) return identity;
+      const parent = parentSubjectId();
+      if (parent === void 0)
+        return { ok: false, code: "absent", message: "this managed execution has no Radar parent subject" };
+      return client.communicationPublish({
+        ...request,
+        sender_agent_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 });
+    },
+    async get(handoff_id) {
+      const identity = await agentId();
+      if (identity.ok === false) return identity;
+      return client.communicationGet({ agent_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 });
+    }
+  };
+}
+
 // extension/radar-execution.ts
 var radar_execution_exports = {};
 __export(radar_execution_exports, {
@@ -1173,6 +1309,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 +1690,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 +1712,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 +1959,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 +1985,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 +2055,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 +2089,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 +2110,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 +2146,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();
     },
@@ -2187,8 +2423,10 @@ function createRadarPublicationInner(options) {
       const record = await ensureRegistration();
       if (record === void 0) return void 0;
       const location = record.registration.location;
+      const subjectId = process.env.PI_RADAR_MANAGED_SUBJECT_ID;
       return {
         agent_id: agentId2,
+        ...subjectId !== void 0 ? { subject_id: subjectId } : {},
         ...location !== void 0 ? { location } : {}
       };
     },
@@ -2326,11 +2564,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 +2632,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 +2850,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 +2883,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: {
@@ -2760,6 +3028,10 @@ async function launchRadarWorker(options) {
     return refusedLaunch(
       "the launch has no exact parent registration to spawn under"
     );
+  if (!isUuid(launch.parent.subject_id))
+    return refusedLaunch(
+      "the launch has no managed Radar subject for its parent"
+    );
   if (pane === void 0 || pane === "")
     return refusedLaunch(
       "this process's Radar registration names no pane, so it cannot be a spawn parent"
@@ -2769,6 +3041,7 @@ async function launchRadarWorker(options) {
     parent: launch.parent.agent_id,
     parent_session_id: launch.parent_session_id,
     executable: launch.executable,
+    managed: { parent_subject_id: launch.parent.subject_id },
     argv: launch.argv,
     ...launch.cwd !== "" ? { cwd: launch.cwd } : {},
     ...Object.keys(launch.env).length > 0 ? { env: launch.env } : {}
@@ -2895,11 +3168,57 @@ 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 = 2;
+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_communication_exports as communication,
   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,39 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createRadarClient } from "./radar-client.ts";
+import { createRadarHandoffPort } from "./radar-communication.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,
+		communication: createRadarHandoffPort(client, execution.publication),
+		execution,
+	}));
+	provideRadarRuntime(pi.events, runtime);
+}