pi-radar 0.1.0 → 0.2.0

package/dist/extension/radar-client.js

@@ -4,7 +4,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";
@@ -224,6 +224,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,
@@ -368,9 +373,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) {
@@ -781,7 +800,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
             },

package/dist/extension/radar-execution.js

@@ -110,6 +110,77 @@ import {
   writeSync
 } from "node:fs";
 import { dirname, join, 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;
@@ -417,15 +488,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 = numberAt(value, "sequence");
   const lease = numberAt(value, "lease_ms");
   const observed = textAt(value, "observed_at");
@@ -433,7 +510,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;
@@ -672,6 +757,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;
@@ -697,9 +783,17 @@ function createContextWriter(input) {
     const generation = numberAt(writer, "generation");
     if (writer !== void 0 && (!exactKeys(writer, WRITER_KEYS) || !isUuid(handle) || generation === void 0))
       return blank(agentId);
-    const pending = contextReportAt(recordAt(value, "pending"), CONTEXT_PENDING_KEYS);
+    const pending = contextReportAt(
+      recordAt(value, "pending"),
+      CONTEXT_PENDING_KEYS,
+      CONTEXT_PENDING_MARKED_KEYS
+    );
     const acceptedValue = recordAt(value, "accepted");
-    const accepted = contextReportAt(acceptedValue, CONTEXT_ACCEPTED_KEYS);
+    const accepted = contextReportAt(
+      acceptedValue,
+      CONTEXT_ACCEPTED_KEYS,
+      CONTEXT_ACCEPTED_MARKED_KEYS
+    );
     const sentAt = numberAt(acceptedValue, "sent_at");
     return {
       version: RADAR_PUBLICATION_VERSION,
@@ -759,7 +853,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;
@@ -790,12 +887,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();
@@ -810,11 +908,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;
@@ -846,9 +944,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();
     },
@@ -1260,11 +1360,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 {
     }
   }
@@ -1328,8 +1428,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;

package/dist/extension/radar-location.js

@@ -63,7 +63,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;
@@ -95,7 +96,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: {

package/dist/extension/radar-publication.js

@@ -15,6 +15,27 @@ import {
 } from "node:fs";
 import { dirname, join, parse, resolve, sep } from "node:path";
 
+// extension/radar-session-marker.ts
+var RADAR_LAUNCH_MARKER_VERSION = 1;
+var RADAR_MAX_EXECUTION_GENERATION = 4294967295;
+var UUID = /^[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" || !UUID.test(record.subject_id) || typeof record.launch_id !== "string" || !UUID.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
+  };
+}
+
 // extension/radar-client.ts
 var RADAR_MAX_LINE_BYTES = 1024 * 1024;
 var wallClock = { setTimeout, clearTimeout, setInterval, clearInterval };
@@ -32,9 +53,9 @@ function bounded(text, bytes) {
     end -= 1;
   return text.slice(0, end);
 }
-var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function isUuid(value) {
-  return typeof value === "string" && UUID.test(value);
+  return typeof value === "string" && UUID2.test(value);
 }
 var RADAR_MAX_BACKGROUND_TASKS = 64;
 var RADAR_MAX_AWAITED = 64;
@@ -422,15 +443,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 = numberAt(value, "sequence");
   const lease = numberAt(value, "lease_ms");
   const observed = textAt(value, "observed_at");
@@ -438,7 +465,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;
@@ -677,6 +712,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;
@@ -702,9 +738,17 @@ function createContextWriter(input) {
     const generation = numberAt(writer, "generation");
     if (writer !== void 0 && (!exactKeys(writer, WRITER_KEYS) || !isUuid(handle) || generation === void 0))
       return blank(agentId);
-    const pending = contextReportAt(recordAt(value, "pending"), CONTEXT_PENDING_KEYS);
+    const pending = contextReportAt(
+      recordAt(value, "pending"),
+      CONTEXT_PENDING_KEYS,
+      CONTEXT_PENDING_MARKED_KEYS
+    );
     const acceptedValue = recordAt(value, "accepted");
-    const accepted = contextReportAt(acceptedValue, CONTEXT_ACCEPTED_KEYS);
+    const accepted = contextReportAt(
+      acceptedValue,
+      CONTEXT_ACCEPTED_KEYS,
+      CONTEXT_ACCEPTED_MARKED_KEYS
+    );
     const sentAt = numberAt(acceptedValue, "sent_at");
     return {
       version: RADAR_PUBLICATION_VERSION,
@@ -764,7 +808,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;
@@ -795,12 +842,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();
@@ -815,11 +863,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;
@@ -851,9 +899,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();
     },

package/dist/extension/radar-runtime.js

@@ -0,0 +1,42 @@
+// extension/radar-runtime.ts
+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_RUNTIME_REQUEST,
+  RADAR_RUNTIME_VERSION,
+  lazyRadarRuntime,
+  provideRadarRuntime,
+  requestRadarRuntime
+};

package/dist/extension/radar-session-marker.js

@@ -0,0 +1,82 @@
+// 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 UUID = /^[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" || !UUID.test(record.subject_id) || typeof record.launch_id !== "string" || !UUID.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;
+}
+export {
+  RADAR_LAUNCH_MARKER_TYPE,
+  RADAR_LAUNCH_MARKER_VERSION,
+  RADAR_MANAGED_GENERATION_ENV,
+  RADAR_MANAGED_LAUNCH_ENV,
+  RADAR_MANAGED_SUBJECT_ENV,
+  RADAR_MAX_EXECUTION_GENERATION,
+  activeRadarLaunchMarker,
+  appendRadarLaunchMarker,
+  decodeRadarLaunchMarker,
+  latestRadarLaunchMarker,
+  persistRadarLaunchMarker,
+  radarLaunchMarkerFromEnvironment
+};