pi-radar 0.5.1 → 0.7.0

package/README.md

@@ -15,11 +15,17 @@ Focused subpaths are also exported: `pi-radar/client`, `pi-radar/communication`,
 
 Installing `pi-radar` directly as a Pi package loads `extension/baseline.ts`, which creates one baseline publisher and exposes its lazy runtime handle through Pi's event bus. Herdsman must request that handle rather than starting another `RadarExecutionAdapter`. Do not load the baseline extension with an older Herdsman integration that still creates its own publisher; first migrate Herdsman to the runtime handle.
 
-The baseline reports session presence through one flat request. A fresh `session_start` creates a claim; heartbeat/reconnect retries reuse it. `publication.presence.management()` reports `managed`, `duplicate`, `pending` or `unmanaged`; `session_shutdown` awaits release of the exact claim. A duplicate remains rejected until a fresh Pi session load. `subject()` returns Radar's current subject only after a grant; no session marker is written to the Pi transcript.
+The baseline reports session presence through one flat request. The first managed `session_start` uses its pre-minted launch claim; subsequent session loads create fresh claims. Heartbeat/reconnect retries reuse the same claim. `publication.presence.management()` reports `managed`, `duplicate`, `pending` or `unmanaged`; `session_shutdown` awaits release of the exact claim. A duplicate remains rejected until a fresh Pi session load. `subject()` returns Radar's current subject only after a grant; no session marker is written to the Pi transcript.
 
 ## Daemon contract
 
-The client speaks protocol 2 and requires wire revision 4. Revision 3 made lifecycle `subject_id` a stable logical identity and exposed the exact current `execution_id` and `u32` generation separately; revision 4 added Pi presence (`agent.presence`/`agent.release`), which is how a session acquires its subject, so a revision-3 daemon would accept the handshake and then leave every Pi session unmanaged. Handoff methods additionally require the independently negotiated `communication.handoff.v1` contract; its timestamps remain exactly representable as JSON numbers. Clients that control managed executions must not target the legacy per-execution ID semantics. It reads `revision` and the public `contracts` list from `daemon.ping`, preserves unfamiliar contract names, and preflights only contracts needed for a multi-step or versioned operation. Backend `mux.*` primitives are private to the daemon; direct mux methods are dispatched and return the daemon's backend refusal when unavailable.
+**Managed execution:** a launch Radar admits arrives with `PI_RADAR_REGISTRATION_ID` in its environment. The baseline captures it, removes it from this process's environment before any child starts, and reports it as `registration_id`, so a managed launch binds the registration Radar already allocated instead of registering itself. A session claim is still fresh per load, and a reload or `/resume` takes a new one under the same registration; nothing about the process identity is presented or reused as a claim. `launch.admit` is the method `radar run` uses and is not part of the client surface. `agent.list` entries and observation agents carry `scoped`: `true` for a process Radar launched into a scope, `false` for an observed process it did not.
+
+**0.7.0 upgrade:** update Radar (0.3.0) and pi-radar together; the floor is wire revision 6. A managed launch now carries `PI_RADAR_REGISTRATION_ID` instead of a claim id, and pi-radar always presents its own fresh claim. Nothing in your code changes unless you read the launch environment directly.
+
+**0.6.0 upgrade:** update Radar and pi-radar together. Lifecycle controls require both `subject_id` and `claim_id`; handoff identities and spawn edges use `claim_id`, with no execution generation. Do not pass an agent's subject id where an attempt is required. Existing private launch records remain readable.
+
+pi-radar 0.7.0 speaks protocol 2 and requires wire revision 6. Revision 6 gives a managed launch its process identity up front: Radar mints the `registration_id`, passes it as `PI_RADAR_REGISTRATION_ID`, and holds a `reserved` claim that grants nothing until the first verified report replaces it with the session's own claim, so a 0.6.0 client, which spends the spawn token as its first claim, cannot bind. Revision 4 added Pi presence (`agent.presence`/`agent.release`), which is how a session acquires its subject. Revision 5 names the agent `subject_id` and one attempt `claim_id`, drops the execution-generation ordinal, and requires lifecycle controls to name the claim they were issued against, so a revision-4 client would read those fields with the old meanings. Handoff methods additionally require the independently negotiated `communication.handoff.v1` contract; its timestamps remain exactly representable as JSON numbers. Clients that control managed executions must not target the legacy per-execution ID semantics. It reads `revision` and the public `contracts` list from `daemon.ping`, preserves unfamiliar contract names, and preflights only contracts needed for a multi-step or versioned operation. Backend `mux.*` primitives are private to the daemon; direct mux methods are dispatched and return the daemon's backend refusal when unavailable.
 
 The client uses `registry.v1` for registry operations and additionally requires `registry.facts.v1` for the facts channel and assignment extensions. Managed children require `spawn.v1`, child-pane removal requires `spawn.close.v1`, event reads require `events.v1`, and handoff operations require `communication.handoff.v1`. The expected wire examples are maintained in this repository's `docs/control-plane.fixture.jsonl` and `docs/agent-registration.fixture.jsonl` and are exercised by the package tests.
 
@@ -41,6 +47,74 @@ Lifecycle execution generations are bounded to `u32` and remain exactly represen
 
 Run `npm pack` to build the bundled runtime entrypoints before creating the tarball.
 
+## Testing against this SDK
+
+Fake the port, not the daemon. Every consumer-facing class here depends on a
+narrow `Pick` of the client, so a test double implements a handful of methods and
+no socket, framing, IDs, error envelope or durable state:
+
+| Port | Methods | Where |
+| --- | --- | --- |
+| `RadarPublicationClient` | `ping`, `presence`, `releasePresence`, `acquire`, `publish`, `retire` | `pi-radar/publication` |
+| `RadarHandoffPort` | `publish`, `inbox`, `get`, `ack` | `pi-radar/communication` |
+| anything else | `Pick<RadarClient, ...>` of the reads you call | `pi-radar/client` |
+
+```ts
+import type { RadarPublicationClient } from "pi-radar/publication";
+import { createRadarPublication } from "pi-radar/publication";
+
+const client: RadarPublicationClient = {
+	ping: async () => ({
+		ok: true,
+		value: {
+			protocol: 2, backend: "tmux", revision: 4, instance: null,
+			contracts: ["registry.v1"], tasks: { available: false, error: null },
+		},
+	}),
+	presence: async (report) => ({
+		ok: true,
+		value: {
+			registration_id: REGISTRATION,
+			claim_id: report.claim_id,
+			standing: "granted",
+			subject_id: SUBJECT,
+		},
+	}),
+	releasePresence: async (release) => ({
+		ok: true,
+		value: {
+			registration_id: release.registration_id,
+			claim_id: release.claim_id,
+			standing: "released",
+		},
+	}),
+	acquire: async () => ({
+		ok: true,
+		value: {
+			handle: "writer", source: "consumer", incarnation: INCARNATION,
+			generation: 1, sequence: 0,
+		},
+	}),
+	publish: async ({ sequence }) => ({ ok: true, value: { sequence } }),
+	retire: async () => ({ ok: true, value: undefined }),
+};
+
+const publication = createRadarPublication({
+	dataRoot, client, registration: { source: "consumer", label: "lead" },
+});
+```
+
+A socket-level fake daemon is a second implementation of Radar's protocol
+maintained by someone who does not own it. It drifts silently: it keeps passing
+while the real daemon refuses the same call, which is worse than having no fake
+at all. That is not hypothetical — a consumer's fake still answered the retired
+registration methods after the daemon had moved to presence, and its suite stayed
+green through the whole contract change.
+
+Wire-level proof belongs to one integration test against the real daemon (a
+temporary socket path and state root are enough; `tests/agent_publisher.py` in
+the Radar repository shows the shape), not to a fake every consumer re-implements.
+
 ## Releasing
 
 Publishing is one tag push and it runs in CI; no npm token is stored anywhere.

package/dist/extension/baseline.js

@@ -8,10 +8,11 @@ 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 = 4;
+var RADAR_MINIMUM_REVISION = 6;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";
+var RADAR_SPAWN_LIST_CONTRACT = "spawn.list.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";
@@ -118,7 +119,7 @@ function decodePresenceAnswer(value) {
   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 !== void 0 && !isUuid(subjectId) || standing === "granted" && !isUuid(subjectId))
+  if (!isUuid(registrationId) || !isUuid(claimId) || !["reserved", "pending", "granted", "duplicate", "released"].includes(String(standing)) || subjectId !== void 0 && !isUuid(subjectId) || standing === "granted" && !isUuid(subjectId))
     return protocol("presence reply carries no valid claim standing");
   return { ok: true, value };
 }
@@ -146,22 +147,20 @@ 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, "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 === 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;
+  if (version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "registration_id")) || !isUuid(stringAt(sender, "session_id")) || !isUuid(stringAt(sender, "subject_id")) || !isUuid(stringAt(sender, "claim_id")) || !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, "registration_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;
+  if (version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "registration_id")) || !isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) || !isUuid(stringAt(recipient, "claim_id")) || received === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
   return value;
 }
 function writerBinding(value) {
@@ -265,7 +264,7 @@ function unresolvedOperation(requestId, detail) {
     message: `focus ${requestId} is unresolved (${detail})`
   };
 }
-var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
+var RADAR_REGISTRATION_ENV = "PI_RADAR_REGISTRATION_ID";
 var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
   "PI_RADAR_MANAGED_SUBJECT_ID",
   "PI_RADAR_MANAGED_LAUNCH_ID",
@@ -414,8 +413,8 @@ function spawnRequestShape(request) {
   const env = Object.entries(request.env ?? {});
   if (env.length > 256) return "spawn env names more than 256 entries";
   for (const [name, value] of env) {
-    if (name === RADAR_SPAWN_TOKEN_ENV)
-      return `spawn env cannot set the reserved ${RADAR_SPAWN_TOKEN_ENV}`;
+    if (name === RADAR_REGISTRATION_ENV)
+      return `spawn env cannot set the reserved ${RADAR_REGISTRATION_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))
@@ -621,6 +620,7 @@ function createRadarClient(options = {}) {
       };
     return answer;
   };
+  let processRegistrationId;
   let handshake;
   const negotiated = async () => {
     handshake ??= probe();
@@ -702,6 +702,7 @@ function createRadarClient(options = {}) {
         const record = answer.value.registration;
         const agentId = stringAt(record, "registration_id");
         if (!isUuid(agentId)) return protocol("registration reply carries no registration_id");
+        processRegistrationId = agentId;
         return { ok: true, value: { registration_id: agentId } };
       });
     },
@@ -835,6 +836,31 @@ function createRadarClient(options = {}) {
         }
       );
     },
+    async spawnList(request) {
+      const registrationId = processRegistrationId;
+      if (registrationId === void 0)
+        return { ok: false, code: "refused", message: "spawn.list requires this client's process registration" };
+      return withContract(RADAR_SPAWN_LIST_CONTRACT, async () => {
+        const params = {
+          registration_id: registrationId,
+          ...request.after !== void 0 ? { after: request.after } : {},
+          ...request.limit !== void 0 ? { limit: request.limit } : {}
+        };
+        const answer = await call("spawn.list", { ...params });
+        if (answer.ok === false) return answer;
+        const spawns = recordAt(answer.value, "spawns");
+        const next = recordAt(answer.value, "next");
+        if (!Array.isArray(spawns) || next != null && !isUuid(next))
+          return protocol("spawn.list reply carries no valid page");
+        for (const spawn of spawns) {
+          const decoded = spawnTopology(spawn);
+          if (decoded.ok === false) return decoded;
+          if (typeof recordAt(spawn, "version") !== "number" || typeof recordAt(spawn, "recorded_at") !== "string" || !["unbound", "bound", "unresolved"].includes(String(recordAt(spawn, "state"))))
+            return protocol("spawn.list reply carries an incomplete topology");
+        }
+        return { ok: true, value: answer.value };
+      });
+    },
     async spawnGet(requestId) {
       if (!isUuid(requestId))
         return {
@@ -1392,7 +1418,13 @@ function createRadarProcessSlot() {
 }
 function radarProcessSlot() {
   const host = globalThis;
-  return host[PROCESS_SLOT] ??= createRadarProcessSlot();
+  if (!host[PROCESS_SLOT]) {
+    const slot = createRadarProcessSlot();
+    slot.launchRegistrationId = process.env.PI_RADAR_REGISTRATION_ID;
+    delete process.env.PI_RADAR_REGISTRATION_ID;
+    host[PROCESS_SLOT] = slot;
+  }
+  return host[PROCESS_SLOT];
 }
 function radarProcessIncarnation(slot = radarProcessSlot()) {
   return slot.incarnation ??= randomUUID2();
@@ -1943,8 +1975,8 @@ function createRadarPublicationInner(options) {
   const store = options.store ?? createPublicationStore(dataRoot);
   const scheduler = options.scheduler ?? systemScheduler;
   const client = options.client;
-  const spawnToken = options.spawnToken;
   const slot = options.slot ?? radarProcessSlot();
+  const launchRegistrationId = options.launchRegistrationId ?? slot.launchRegistrationId;
   const incarnation = options.incarnation ?? radarProcessIncarnation(slot);
   const cacheKey = `${options.store === void 0 ? dataRoot : storeIdentity(options.store)}\0${incarnation}`;
   const cached = slot.publications.get(cacheKey);
@@ -2068,7 +2100,7 @@ function createRadarPublicationInner(options) {
       return {
         ...identity,
         ...location?.state === "resolved" ? { location: location.location } : {},
-        ...spawnToken ? { spawn_token: spawnToken } : {}
+        ...launchRegistrationId ? { registration_id: launchRegistrationId } : {}
       };
     },
     heartbeatMs: options.heartbeatMs ?? RADAR_HEARTBEAT_MS
@@ -2255,7 +2287,7 @@ function createRadarExecutionAdapter(pi, options) {
       },
       ...options.location !== void 0 ? { location: options.location } : {},
       ...managed !== void 0 ? { binding: managed } : {},
-      ...options.spawnToken !== void 0 ? { spawnToken: options.spawnToken } : {}
+      ...options.launchRegistrationId !== void 0 ? { launchRegistrationId: options.launchRegistrationId } : {}
     });
   } catch {
     publication = unavailablePublication2();

package/dist/extension/radar-client.js

@@ -4,10 +4,11 @@ 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 = 4;
+var RADAR_MINIMUM_REVISION = 6;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";
+var RADAR_SPAWN_LIST_CONTRACT = "spawn.list.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";
@@ -114,7 +115,7 @@ function decodePresenceAnswer(value) {
   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 !== void 0 && !isUuid(subjectId) || standing === "granted" && !isUuid(subjectId))
+  if (!isUuid(registrationId) || !isUuid(claimId) || !["reserved", "pending", "granted", "duplicate", "released"].includes(String(standing)) || subjectId !== void 0 && !isUuid(subjectId) || standing === "granted" && !isUuid(subjectId))
     return protocol("presence reply carries no valid claim standing");
   return { ok: true, value };
 }
@@ -142,22 +143,20 @@ 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, "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 === 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;
+  if (version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "registration_id")) || !isUuid(stringAt(sender, "session_id")) || !isUuid(stringAt(sender, "subject_id")) || !isUuid(stringAt(sender, "claim_id")) || !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, "registration_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;
+  if (version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "registration_id")) || !isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) || !isUuid(stringAt(recipient, "claim_id")) || received === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
   return value;
 }
 function writerBinding(value) {
@@ -265,7 +264,7 @@ function unresolvedOperation(requestId, detail) {
     message: `focus ${requestId} is unresolved (${detail})`
   };
 }
-var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
+var RADAR_REGISTRATION_ENV = "PI_RADAR_REGISTRATION_ID";
 var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
   "PI_RADAR_MANAGED_SUBJECT_ID",
   "PI_RADAR_MANAGED_LAUNCH_ID",
@@ -414,8 +413,8 @@ function spawnRequestShape(request) {
   const env = Object.entries(request.env ?? {});
   if (env.length > 256) return "spawn env names more than 256 entries";
   for (const [name, value] of env) {
-    if (name === RADAR_SPAWN_TOKEN_ENV)
-      return `spawn env cannot set the reserved ${RADAR_SPAWN_TOKEN_ENV}`;
+    if (name === RADAR_REGISTRATION_ENV)
+      return `spawn env cannot set the reserved ${RADAR_REGISTRATION_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))
@@ -679,6 +678,7 @@ function createRadarClient(options = {}) {
       };
     return answer;
   };
+  let processRegistrationId;
   let handshake;
   const negotiated = async () => {
     handshake ??= probe();
@@ -760,6 +760,7 @@ function createRadarClient(options = {}) {
         const record = answer.value.registration;
         const agentId = stringAt(record, "registration_id");
         if (!isUuid(agentId)) return protocol("registration reply carries no registration_id");
+        processRegistrationId = agentId;
         return { ok: true, value: { registration_id: agentId } };
       });
     },
@@ -893,6 +894,31 @@ function createRadarClient(options = {}) {
         }
       );
     },
+    async spawnList(request) {
+      const registrationId = processRegistrationId;
+      if (registrationId === void 0)
+        return { ok: false, code: "refused", message: "spawn.list requires this client's process registration" };
+      return withContract(RADAR_SPAWN_LIST_CONTRACT, async () => {
+        const params = {
+          registration_id: registrationId,
+          ...request.after !== void 0 ? { after: request.after } : {},
+          ...request.limit !== void 0 ? { limit: request.limit } : {}
+        };
+        const answer = await call("spawn.list", { ...params });
+        if (answer.ok === false) return answer;
+        const spawns = recordAt(answer.value, "spawns");
+        const next = recordAt(answer.value, "next");
+        if (!Array.isArray(spawns) || next != null && !isUuid(next))
+          return protocol("spawn.list reply carries no valid page");
+        for (const spawn of spawns) {
+          const decoded = spawnTopology(spawn);
+          if (decoded.ok === false) return decoded;
+          if (typeof recordAt(spawn, "version") !== "number" || typeof recordAt(spawn, "recorded_at") !== "string" || !["unbound", "bound", "unresolved"].includes(String(recordAt(spawn, "state"))))
+            return protocol("spawn.list reply carries an incomplete topology");
+        }
+        return { ok: true, value: answer.value };
+      });
+    },
     async spawnGet(requestId) {
       if (!isUuid(requestId))
         return {
@@ -1244,13 +1270,14 @@ export {
   RADAR_MAX_LINE_BYTES,
   RADAR_MINIMUM_REVISION,
   RADAR_PROTOCOL_VERSION,
+  RADAR_REGISTRATION_ENV,
   RADAR_REGISTRY_CONTRACT,
   RADAR_REGISTRY_FACTS_CONTRACT,
   RADAR_REQUESTER,
   RADAR_SPAWN_CLOSE_CONTRACT,
   RADAR_SPAWN_CONTRACT,
   RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT,
-  RADAR_SPAWN_TOKEN_ENV,
+  RADAR_SPAWN_LIST_CONTRACT,
   boundedRadarAssignment,
   boundedRadarFacts,
   boundedRadarSnapshot,

package/dist/extension/radar-execution.js

@@ -272,7 +272,13 @@ function createRadarProcessSlot() {
 }
 function radarProcessSlot() {
   const host = globalThis;
-  return host[PROCESS_SLOT] ??= createRadarProcessSlot();
+  if (!host[PROCESS_SLOT]) {
+    const slot = createRadarProcessSlot();
+    slot.launchRegistrationId = process.env.PI_RADAR_REGISTRATION_ID;
+    delete process.env.PI_RADAR_REGISTRATION_ID;
+    host[PROCESS_SLOT] = slot;
+  }
+  return host[PROCESS_SLOT];
 }
 function radarProcessIncarnation(slot = radarProcessSlot()) {
   return slot.incarnation ??= randomUUID();
@@ -823,8 +829,8 @@ function createRadarPublicationInner(options) {
   const store = options.store ?? createPublicationStore(dataRoot);
   const scheduler = options.scheduler ?? systemScheduler;
   const client = options.client;
-  const spawnToken = options.spawnToken;
   const slot = options.slot ?? radarProcessSlot();
+  const launchRegistrationId = options.launchRegistrationId ?? slot.launchRegistrationId;
   const incarnation = options.incarnation ?? radarProcessIncarnation(slot);
   const cacheKey = `${options.store === void 0 ? dataRoot : storeIdentity(options.store)}\0${incarnation}`;
   const cached = slot.publications.get(cacheKey);
@@ -948,7 +954,7 @@ function createRadarPublicationInner(options) {
       return {
         ...identity,
         ...location?.state === "resolved" ? { location: location.location } : {},
-        ...spawnToken ? { spawn_token: spawnToken } : {}
+        ...launchRegistrationId ? { registration_id: launchRegistrationId } : {}
       };
     },
     heartbeatMs: options.heartbeatMs ?? RADAR_HEARTBEAT_MS
@@ -1141,7 +1147,7 @@ function createRadarExecutionAdapter(pi, options) {
       },
       ...options.location !== void 0 ? { location: options.location } : {},
       ...managed !== void 0 ? { binding: managed } : {},
-      ...options.spawnToken !== void 0 ? { spawnToken: options.spawnToken } : {}
+      ...options.launchRegistrationId !== void 0 ? { launchRegistrationId: options.launchRegistrationId } : {}
     });
   } catch {
     publication = unavailablePublication2();

package/dist/extension/radar-publication.js

@@ -274,7 +274,13 @@ function createRadarProcessSlot() {
 }
 function radarProcessSlot() {
   const host = globalThis;
-  return host[PROCESS_SLOT] ??= createRadarProcessSlot();
+  if (!host[PROCESS_SLOT]) {
+    const slot = createRadarProcessSlot();
+    slot.launchRegistrationId = process.env.PI_RADAR_REGISTRATION_ID;
+    delete process.env.PI_RADAR_REGISTRATION_ID;
+    host[PROCESS_SLOT] = slot;
+  }
+  return host[PROCESS_SLOT];
 }
 function radarProcessIncarnation(slot = radarProcessSlot()) {
   return slot.incarnation ??= randomUUID();
@@ -828,8 +834,8 @@ function createRadarPublicationInner(options) {
   const store = options.store ?? createPublicationStore(dataRoot);
   const scheduler = options.scheduler ?? systemScheduler;
   const client = options.client;
-  const spawnToken = options.spawnToken;
   const slot = options.slot ?? radarProcessSlot();
+  const launchRegistrationId = options.launchRegistrationId ?? slot.launchRegistrationId;
   const incarnation = options.incarnation ?? radarProcessIncarnation(slot);
   const cacheKey = `${options.store === void 0 ? dataRoot : storeIdentity(options.store)}\0${incarnation}`;
   const cached = slot.publications.get(cacheKey);
@@ -953,7 +959,7 @@ function createRadarPublicationInner(options) {
       return {
         ...identity,
         ...location?.state === "resolved" ? { location: location.location } : {},
-        ...spawnToken ? { spawn_token: spawnToken } : {}
+        ...launchRegistrationId ? { registration_id: launchRegistrationId } : {}
       };
     },
     heartbeatMs: options.heartbeatMs ?? RADAR_HEARTBEAT_MS

package/dist/index.js

@@ -16,13 +16,14 @@ __export(radar_client_exports, {
   RADAR_MAX_LINE_BYTES: () => RADAR_MAX_LINE_BYTES,
   RADAR_MINIMUM_REVISION: () => RADAR_MINIMUM_REVISION,
   RADAR_PROTOCOL_VERSION: () => RADAR_PROTOCOL_VERSION,
+  RADAR_REGISTRATION_ENV: () => RADAR_REGISTRATION_ENV,
   RADAR_REGISTRY_CONTRACT: () => RADAR_REGISTRY_CONTRACT,
   RADAR_REGISTRY_FACTS_CONTRACT: () => RADAR_REGISTRY_FACTS_CONTRACT,
   RADAR_REQUESTER: () => RADAR_REQUESTER,
   RADAR_SPAWN_CLOSE_CONTRACT: () => RADAR_SPAWN_CLOSE_CONTRACT,
   RADAR_SPAWN_CONTRACT: () => RADAR_SPAWN_CONTRACT,
   RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT: () => RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT,
-  RADAR_SPAWN_TOKEN_ENV: () => RADAR_SPAWN_TOKEN_ENV,
+  RADAR_SPAWN_LIST_CONTRACT: () => RADAR_SPAWN_LIST_CONTRACT,
   boundedRadarAssignment: () => boundedRadarAssignment,
   boundedRadarFacts: () => boundedRadarFacts,
   boundedRadarSnapshot: () => boundedRadarSnapshot,
@@ -39,10 +40,11 @@ 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 = 4;
+var RADAR_MINIMUM_REVISION = 6;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";
+var RADAR_SPAWN_LIST_CONTRACT = "spawn.list.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";
@@ -149,7 +151,7 @@ function decodePresenceAnswer(value) {
   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 !== void 0 && !isUuid(subjectId) || standing === "granted" && !isUuid(subjectId))
+  if (!isUuid(registrationId) || !isUuid(claimId) || !["reserved", "pending", "granted", "duplicate", "released"].includes(String(standing)) || subjectId !== void 0 && !isUuid(subjectId) || standing === "granted" && !isUuid(subjectId))
     return protocol("presence reply carries no valid claim standing");
   return { ok: true, value };
 }
@@ -177,22 +179,20 @@ 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, "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 === 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;
+  if (version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "registration_id")) || !isUuid(stringAt(sender, "session_id")) || !isUuid(stringAt(sender, "subject_id")) || !isUuid(stringAt(sender, "claim_id")) || !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, "registration_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;
+  if (version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "registration_id")) || !isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) || !isUuid(stringAt(recipient, "claim_id")) || received === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
   return value;
 }
 function writerBinding(value) {
@@ -300,7 +300,7 @@ function unresolvedOperation(requestId, detail) {
     message: `focus ${requestId} is unresolved (${detail})`
   };
 }
-var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
+var RADAR_REGISTRATION_ENV = "PI_RADAR_REGISTRATION_ID";
 var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
   "PI_RADAR_MANAGED_SUBJECT_ID",
   "PI_RADAR_MANAGED_LAUNCH_ID",
@@ -449,8 +449,8 @@ function spawnRequestShape(request) {
   const env = Object.entries(request.env ?? {});
   if (env.length > 256) return "spawn env names more than 256 entries";
   for (const [name, value] of env) {
-    if (name === RADAR_SPAWN_TOKEN_ENV)
-      return `spawn env cannot set the reserved ${RADAR_SPAWN_TOKEN_ENV}`;
+    if (name === RADAR_REGISTRATION_ENV)
+      return `spawn env cannot set the reserved ${RADAR_REGISTRATION_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))
@@ -714,6 +714,7 @@ function createRadarClient(options = {}) {
       };
     return answer;
   };
+  let processRegistrationId;
   let handshake;
   const negotiated = async () => {
     handshake ??= probe();
@@ -795,6 +796,7 @@ function createRadarClient(options = {}) {
         const record = answer.value.registration;
         const agentId = stringAt(record, "registration_id");
         if (!isUuid(agentId)) return protocol("registration reply carries no registration_id");
+        processRegistrationId = agentId;
         return { ok: true, value: { registration_id: agentId } };
       });
     },
@@ -928,6 +930,31 @@ function createRadarClient(options = {}) {
         }
       );
     },
+    async spawnList(request) {
+      const registrationId = processRegistrationId;
+      if (registrationId === void 0)
+        return { ok: false, code: "refused", message: "spawn.list requires this client's process registration" };
+      return withContract(RADAR_SPAWN_LIST_CONTRACT, async () => {
+        const params = {
+          registration_id: registrationId,
+          ...request.after !== void 0 ? { after: request.after } : {},
+          ...request.limit !== void 0 ? { limit: request.limit } : {}
+        };
+        const answer = await call("spawn.list", { ...params });
+        if (answer.ok === false) return answer;
+        const spawns = recordAt(answer.value, "spawns");
+        const next = recordAt(answer.value, "next");
+        if (!Array.isArray(spawns) || next != null && !isUuid(next))
+          return protocol("spawn.list reply carries no valid page");
+        for (const spawn of spawns) {
+          const decoded = spawnTopology(spawn);
+          if (decoded.ok === false) return decoded;
+          if (typeof recordAt(spawn, "version") !== "number" || typeof recordAt(spawn, "recorded_at") !== "string" || !["unbound", "bound", "unresolved"].includes(String(recordAt(spawn, "state"))))
+            return protocol("spawn.list reply carries an incomplete topology");
+        }
+        return { ok: true, value: answer.value };
+      });
+    },
     async spawnGet(requestId) {
       if (!isUuid(requestId))
         return {
@@ -1511,7 +1538,13 @@ function createRadarProcessSlot() {
 }
 function radarProcessSlot() {
   const host = globalThis;
-  return host[PROCESS_SLOT] ??= createRadarProcessSlot();
+  if (!host[PROCESS_SLOT]) {
+    const slot = createRadarProcessSlot();
+    slot.launchRegistrationId = process.env.PI_RADAR_REGISTRATION_ID;
+    delete process.env.PI_RADAR_REGISTRATION_ID;
+    host[PROCESS_SLOT] = slot;
+  }
+  return host[PROCESS_SLOT];
 }
 function radarProcessIncarnation(slot = radarProcessSlot()) {
   return slot.incarnation ??= randomUUID2();
@@ -2065,8 +2098,8 @@ function createRadarPublicationInner(options) {
   const store = options.store ?? createPublicationStore(dataRoot);
   const scheduler = options.scheduler ?? systemScheduler;
   const client = options.client;
-  const spawnToken = options.spawnToken;
   const slot = options.slot ?? radarProcessSlot();
+  const launchRegistrationId = options.launchRegistrationId ?? slot.launchRegistrationId;
   const incarnation = options.incarnation ?? radarProcessIncarnation(slot);
   const cacheKey = `${options.store === void 0 ? dataRoot : storeIdentity(options.store)}\0${incarnation}`;
   const cached = slot.publications.get(cacheKey);
@@ -2190,7 +2223,7 @@ function createRadarPublicationInner(options) {
       return {
         ...identity,
         ...location?.state === "resolved" ? { location: location.location } : {},
-        ...spawnToken ? { spawn_token: spawnToken } : {}
+        ...launchRegistrationId ? { registration_id: launchRegistrationId } : {}
       };
     },
     heartbeatMs: options.heartbeatMs ?? RADAR_HEARTBEAT_MS
@@ -2383,7 +2416,7 @@ function createRadarExecutionAdapter(pi, options) {
       },
       ...options.location !== void 0 ? { location: options.location } : {},
       ...managed !== void 0 ? { binding: managed } : {},
-      ...options.spawnToken !== void 0 ? { spawnToken: options.spawnToken } : {}
+      ...options.launchRegistrationId !== void 0 ? { launchRegistrationId: options.launchRegistrationId } : {}
     });
   } catch {
     publication = unavailablePublication2();