pi-radar 0.5.1 → 0.6.0

package/README.md

@@ -15,11 +15,13 @@ 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.
+**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.6.0 speaks protocol 2 and requires wire revision 5. 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: the floor is 5. 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 +43,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 = 5;
 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";
@@ -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) {
@@ -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 {
@@ -1822,6 +1848,11 @@ function createPresenceReporter(input) {
       await releasePending();
       const registration = await input.registration();
       if (!registration?.process || state !== claim || stopped) return void 0;
+      if (claim.initial_load) {
+        if (registration.spawn_token) claim.claim_id = registration.spawn_token;
+        claim.initial_load = false;
+        if (!save()) return void 0;
+      }
       const answer = await client.presence({
         ...registration,
         process: registration.process,
@@ -1860,7 +1891,7 @@ function createPresenceReporter(input) {
         releases.push({ registration_id: state.registration_id, claim_id: state.claim_id });
       }
       standing = void 0;
-      state = { version: 2, session, claim_id: randomUUID2(), releases };
+      state = { version: 2, session, claim_id: randomUUID2(), initial_load: state === void 0, releases };
       save();
       stopped = false;
       void ensure();

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 = 5;
 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";
@@ -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) {
@@ -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 {
@@ -1250,6 +1276,7 @@ export {
   RADAR_SPAWN_CLOSE_CONTRACT,
   RADAR_SPAWN_CONTRACT,
   RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT,
+  RADAR_SPAWN_LIST_CONTRACT,
   RADAR_SPAWN_TOKEN_ENV,
   boundedRadarAssignment,
   boundedRadarFacts,

package/dist/extension/radar-execution.js

@@ -702,6 +702,11 @@ function createPresenceReporter(input) {
       await releasePending();
       const registration = await input.registration();
       if (!registration?.process || state !== claim || stopped) return void 0;
+      if (claim.initial_load) {
+        if (registration.spawn_token) claim.claim_id = registration.spawn_token;
+        claim.initial_load = false;
+        if (!save()) return void 0;
+      }
       const answer = await client.presence({
         ...registration,
         process: registration.process,
@@ -740,7 +745,7 @@ function createPresenceReporter(input) {
         releases.push({ registration_id: state.registration_id, claim_id: state.claim_id });
       }
       standing = void 0;
-      state = { version: 2, session, claim_id: randomUUID(), releases };
+      state = { version: 2, session, claim_id: randomUUID(), initial_load: state === void 0, releases };
       save();
       stopped = false;
       void ensure();

package/dist/extension/radar-publication.js

@@ -707,6 +707,11 @@ function createPresenceReporter(input) {
       await releasePending();
       const registration = await input.registration();
       if (!registration?.process || state !== claim || stopped) return void 0;
+      if (claim.initial_load) {
+        if (registration.spawn_token) claim.claim_id = registration.spawn_token;
+        claim.initial_load = false;
+        if (!save()) return void 0;
+      }
       const answer = await client.presence({
         ...registration,
         process: registration.process,
@@ -745,7 +750,7 @@ function createPresenceReporter(input) {
         releases.push({ registration_id: state.registration_id, claim_id: state.claim_id });
       }
       standing = void 0;
-      state = { version: 2, session, claim_id: randomUUID(), releases };
+      state = { version: 2, session, claim_id: randomUUID(), initial_load: state === void 0, releases };
       save();
       stopped = false;
       void ensure();

package/dist/index.js

@@ -22,6 +22,7 @@ __export(radar_client_exports, {
   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_LIST_CONTRACT: () => RADAR_SPAWN_LIST_CONTRACT,
   RADAR_SPAWN_TOKEN_ENV: () => RADAR_SPAWN_TOKEN_ENV,
   boundedRadarAssignment: () => boundedRadarAssignment,
   boundedRadarFacts: () => boundedRadarFacts,
@@ -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 = 5;
 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";
@@ -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) {
@@ -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 {
@@ -1944,6 +1971,11 @@ function createPresenceReporter(input) {
       await releasePending();
       const registration = await input.registration();
       if (!registration?.process || state !== claim || stopped) return void 0;
+      if (claim.initial_load) {
+        if (registration.spawn_token) claim.claim_id = registration.spawn_token;
+        claim.initial_load = false;
+        if (!save()) return void 0;
+      }
       const answer = await client.presence({
         ...registration,
         process: registration.process,
@@ -1982,7 +2014,7 @@ function createPresenceReporter(input) {
         releases.push({ registration_id: state.registration_id, claim_id: state.claim_id });
       }
       standing = void 0;
-      state = { version: 2, session, claim_id: randomUUID2(), releases };
+      state = { version: 2, session, claim_id: randomUUID2(), initial_load: state === void 0, releases };
       save();
       stopped = false;
       void ensure();

package/extension/generated-contracts.ts

@@ -151,8 +151,7 @@ export interface HandoffSerialize {
  * generation identify the exact execution that took the action.
  */
 export interface HandoffIdentity {
-  execution_generation: number;
-  execution_id: string;
+  claim_id: string;
   registration_id: string;
   session_id: string;
   subject_id: string;
@@ -172,8 +171,7 @@ export interface HandoffReceiptSerialize {
  * generation identify the exact execution that took the action.
  */
 export interface HandoffIdentity {
-  execution_generation: number;
-  execution_id: string;
+  claim_id: string;
   registration_id: string;
   session_id: string;
   subject_id: string;
@@ -902,6 +900,7 @@ export interface RegistryLocation {
  */
 export interface ManagedSubject {
   child_close: ChildCloseTarget | null;
+  claim_id: string;
   identity_unresolved: boolean;
   metadata: ManagedMetadata;
   process: ProcessIdentity;
@@ -938,10 +937,10 @@ export interface ManagedMetadata {
 export interface SpawnBinding {
   child_incarnation: string | null;
   child_source: string | null;
+  claim_id: string | null;
   parent: string;
   request_id: string;
   state: SpawnState;
-  subject_id: string | null;
 }
 /**
  * What this machine knows about that process. Filled by the collector
@@ -1385,3 +1384,107 @@ export interface ObservationTooLarge {
   limit_bytes: number;
   revision: number;
 }
+/**
+ * Input accepted by `spawn.list`.
+ *
+ * A caller presents itself; the parent whose launches it reads is derived from
+ * the claim it holds. There is deliberately no parent parameter: naming another
+ * subject would let any client read its launches.
+ */
+export interface SpawnListParamsDeserialize {
+  after?: string | null;
+  limit?: number | null;
+  registration_id?: string | null;
+}
+/**
+ * What a completed request did.
+ */
+export type SpawnListPageSerializeRequestOutcome = "completed" | "refused" | "unknown";
+/**
+ * What a spawn topology read can say about a child's process exit.
+ */
+export type SpawnListPageSerializePublicSpawnExitObservation =
+  | {
+      state: "unknown";
+    }
+  | {
+      code: number | null;
+      observed_at: string;
+      signal: number | null;
+      state: "exited";
+    };
+/**
+ * Freshness is independent of process identity or completion.
+ */
+export type SpawnListPageSerializeFreshness = "fresh" | "stale";
+/**
+ * The state of one edge in the recorded topology: the strongest statement a
+ * read can make about it, and nothing beyond the records and this read's own
+ * evidence.
+ */
+export type SpawnListPageSerializeSpawnState = "unbound" | "bound" | "unresolved";
+
+/**
+ * One page of spawn edges. `next` names the request id the page ended on.
+ */
+export interface SpawnListPageSerialize {
+  next?: string | null;
+  spawns: SpawnListPageSerializePublicSpawnTopology[];
+}
+/**
+ * One edge as a topology read reports it: the stored facts, plus the two things
+ * a read derives instead of inferring.
+ */
+export interface SpawnListPageSerializePublicSpawnTopology {
+  bound?: SpawnListPageSerializeBoundChild | null;
+  claim_id?: string | null;
+  created: SpawnListPageSerializeRequestOutcome;
+  exit_observation?: SpawnListPageSerializePublicSpawnExitObservation | null;
+  /**
+   * Freshness of the recorded location against this read's evidence, in the
+   * registry's one freshness vocabulary: `fresh` when the backend reports the
+   * location now, `stale` when it does not — which is never evidence that the
+   * child stopped. Absent when the edge recorded no location, because there is
+   * nothing to verify.
+   */
+  freshness?: SpawnListPageSerializeFreshness | null;
+  launched: SpawnListPageSerializeRequestOutcome;
+  location?: SpawnListPageSerializeRegistryLocation | null;
+  parent: string;
+  parent_session_id?: string | null;
+  parent_subject_id?: string | null;
+  recorded_at: string;
+  request_id: string;
+  state: SpawnListPageSerializeSpawnState;
+  version: number;
+}
+/**
+ * The child a token bound: the registering incarnation's own registry identity.
+ */
+export interface SpawnListPageSerializeBoundChild {
+  /**
+   * When the edge bound to this incarnation.
+   */
+  bound_at: string;
+  incarnation: string;
+  /**
+   * Exact registry identity returned to the registering child. Absent in legacy records.
+   */
+  registration_id?: string | null;
+  source: string;
+}
+/**
+ * Where an agent's incarnation lives on one backend, in that backend's own
+ * coordinates.
+ *
+ * The backend name is free-form so a source Radar does not ship yet is
+ * preserved rather than rejected; the rest are the coordinates as reported, and
+ * each is optional because a backend need not name every level.
+ */
+export interface SpawnListPageSerializeRegistryLocation {
+  backend: string;
+  instance?: string | null;
+  pane?: string | null;
+  tab?: string | null;
+  workspace?: string | null;
+}