pi-radar 0.6.0 → 0.9.0

package/README.md

@@ -19,9 +19,13 @@ The baseline reports session presence through one flat request. The first manage
 
 ## Daemon contract
 
+**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.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.
+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.
 
@@ -31,6 +35,16 @@ The client uses `registry.v1` for registry operations and additionally requires
 
 The handoff API stores immutable bounded content separately from the recipient receipt. `inbox()` returns pending IDs only; retrieve each payload with `get()` and persist it before `ack()`, so a batch cannot exceed the RPC response bound. A worker's first Herdsman handoff is addressed only to the stable `parent_subject_id` recorded by Radar for its accepted managed launch. The parent gets its stable subject ID from `RadarSubject` and supplies it as `RadarWorkerLaunch.parent.subject_id`; `launchRadarWorker` forwards it as `managed.parent_subject_id`, and Radar injects the accepted value into the worker as `PI_RADAR_MANAGED_PARENT_SUBJECT_ID`. The handoff port reads that process context; callers cannot choose a destination. The daemon checks it against the durable parent record. Do not substitute a registration ID, Pi session, owner-session field, pane, or inferred lineage; unmanaged/session routing is deferred. The owner must durably capture the payload locally before calling `ack`; acknowledgement does not settle Herdsman assignment state or authorize worker closure. Pending inbox scans recover work after daemon restart or missed pointer events, and acknowledged content remains retrievable during the retention window. See `docs/control-plane.md` for wire shapes, bounds and recovery semantics.
 
+## Launching a worker
+
+`launchRadarWorker` takes the parent from the caller's own `publication`, so a consumer passes the pane it splits and no registration or subject for the parent. The result names the child by its `subject_id`, the key that stays the same when the child restarts or resumes; keep that as the child's identifier. A received handoff carries its sender's `subject_id`; match children by it.
+
+To start a released child again, pass `continues: subject_id`: the daemon takes the session from its own record, so no session id or path is sent, and it refuses a child that is not yours or is still running. `client.restart` replaces your own live child under a new program. Both need Radar 0.4.0 or newer.
+
+## Addressing children by subject
+
+The runtime's `children` service (`RADAR_RUNTIME_VERSION` 3) is the surface for everything after a launch. `list()` returns the caller's children as `{ subject_id, request_id, pane_id, state, exited }`; `observe`, `inspect`, `assignment` and `retire` take the subject. pi-radar resolves a subject to its newest bound launch on every call and never remembers the process, so a child replaced under the same subject is reached by the same key. A held assignment follows a replaced child: the next `list`, `observe` or `inspect` finds the new process and moves the assignment onto it, retiring it from the old one. Consumers need no registration or claim id.
+
 ## Generated protocol contracts
 
 The selected Rust wire DTOs are the source for the draft 2020-12 schemas in `schema/public/v1/`, shipped and exported under `pi-radar/schema/`. They are this package's contract of record: a daemon change lands as a schema regeneration, and the method-to-schema index lives in `docs/agent-registration.md` in the Radar repository. Serialize and deserialize schemas are separate because Serde defaults, null handling and omission differ by direction. The SDK's ping, Pi presence report/answer/release, handoff inbox, publication-parameter, immutable handoff, receipt, managed-launch-metadata input, facts-input, spawn-exit, and observation request/snapshot/response types are generated into `extension/generated-contracts.ts`; do not edit that file by hand.

package/dist/extension/baseline.js

@@ -8,12 +8,13 @@ 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 = 5;
+var RADAR_MINIMUM_REVISION = 7;
 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_LIFECYCLE_RESTART_CONTRACT = "lifecycle.restart.v1";
 var RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 var RADAR_EVENTS_CONTRACT = "events.v1";
 var RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
@@ -119,7 +120,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 };
 }
@@ -264,7 +265,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",
@@ -315,6 +316,7 @@ function spawnEdge(value) {
   const source = stringAt(bound, "source");
   const incarnation = stringAt(bound, "incarnation");
   const agentId = stringAt(bound, "registration_id");
+  const subjectId = stringAt(bound, "subject_id");
   const exit = exitAt(recordAt(value, "exit_observation"));
   return {
     ok: true,
@@ -328,7 +330,8 @@ function spawnEdge(value) {
         bound: {
           source,
           incarnation,
-          ...isUuid(agentId) ? { registration_id: agentId } : {}
+          ...isUuid(agentId) ? { registration_id: agentId } : {},
+          ...isUuid(subjectId) ? { subject_id: subjectId } : {}
         }
       } : {},
       ...exit !== void 0 ? { exit_observation: exit } : {}
@@ -400,6 +403,8 @@ function spawnTopology(value) {
 function spawnRequestShape(request) {
   if (!isUuid(request.request_id))
     return "spawn requires a canonical request UUID";
+  if (request.continue_subject_id !== void 0 && !isUuid(request.continue_subject_id))
+    return "continue_subject_id must be a canonical UUID";
   if (!isUuid(request.parent))
     return "spawn requires the parent's canonical agent UUID";
   if (!isUuid(request.parent_session_id))
@@ -413,8 +418,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))
@@ -808,7 +813,8 @@ function createRadarClient(options = {}) {
                 argv: request.argv,
                 ...request.cwd !== void 0 ? { cwd: request.cwd } : {},
                 ...carriesContext && request.env !== void 0 ? { env: request.env } : {},
-                ...request.managed !== void 0 ? { managed: request.managed } : {}
+                ...request.managed !== void 0 ? { managed: request.managed } : {},
+                ...request.continue_subject_id !== void 0 ? { continue_subject_id: request.continue_subject_id } : {}
               },
               requester
             },
@@ -836,6 +842,33 @@ function createRadarClient(options = {}) {
         }
       );
     },
+    async restart(request) {
+      if (!isUuid(request.request_id) || !isUuid(request.parent) || !isUuid(request.subject_id))
+        return {
+          ok: false,
+          code: "bad_params",
+          message: "restart requires canonical request, parent and subject UUIDs"
+        };
+      return withContract(RADAR_LIFECYCLE_RESTART_CONTRACT, async () => {
+        const answer = await call(
+          "lifecycle.restart",
+          {
+            request: {
+              subject_id: request.subject_id,
+              parent: request.parent,
+              executable: request.executable,
+              argv: request.argv,
+              ...request.cwd !== void 0 ? { cwd: request.cwd } : {},
+              ...request.env !== void 0 ? { env: request.env } : {}
+            },
+            requester
+          },
+          request.request_id
+        );
+        if (answer.ok === false) return answer;
+        return focusOutcome(recordAt(answer.value, "request"), request.request_id);
+      });
+    },
     async spawnList(request) {
       const registrationId = processRegistrationId;
       if (registrationId === void 0)
@@ -1203,6 +1236,348 @@ function boundedRadarSnapshot(snapshot) {
   };
 }
 
+// extension/radar-inspection.ts
+var INSPECTION_LINES = 80;
+var INSPECTION_OUTPUT_BYTES = 16 * 1024;
+async function provedRead(client, target) {
+  const read = await client.agentGet(target.agentId);
+  return read.ok === true && read.value.verification === "verified" && read.value.location?.pane === target.paneId && (target.session === void 0 || read.value.contextSession === target.session) ? read.value : void 0;
+}
+async function inspectRadarChild(client, target) {
+  const before = await provedRead(client, target);
+  if (before === void 0)
+    throw new Error("Inspection target identity did not match");
+  const output = await client.output({
+    pane_id: target.paneId,
+    source: "recent_unwrapped",
+    lines: INSPECTION_LINES
+  });
+  if (output.ok === false)
+    throw new Error(
+      `Inspection output unavailable (${output.code}: ${output.message})`
+    );
+  const foreground = await client.processInfo({ pane_id: target.paneId });
+  const after = await provedRead(client, target);
+  if (after === void 0)
+    throw new Error("Inspection target changed during capture");
+  const lines = output.value.text.trim().split(/\r?\n/).slice(-INSPECTION_LINES);
+  const bounded2 = utf8Tail(lines.join("\n"), INSPECTION_OUTPUT_BYTES);
+  return Object.freeze({
+    capturedAt: Date.now(),
+    recentOutputTruncated: output.value.truncated || bounded2.truncated,
+    ...bounded2.text ? { recentOutput: bounded2.text } : {},
+    ...foreground.ok === true ? { foreground: foreground.value } : {},
+    ...after.activity !== void 0 ? { activity: after.activity } : {}
+  });
+}
+function utf8Tail(value, maxBytes) {
+  const bytes = Buffer.from(value);
+  if (bytes.length <= maxBytes) return { text: value, truncated: false };
+  let start = bytes.length - maxBytes;
+  while (start < bytes.length && (bytes[start] & 192) === 128) start++;
+  return { text: bytes.subarray(start).toString(), truncated: true };
+}
+
+// extension/radar-location.ts
+import { basename } from "node:path";
+function radarLocalPane(env) {
+  const pane = env.TMUX_PANE?.trim();
+  return pane && /^%\d+$/.test(pane) ? pane : void 0;
+}
+function tmuxServerName(env) {
+  const socket = env.TMUX?.trim().split(",")[0];
+  return socket ? basename(socket) || void 0 : void 0;
+}
+function qualifiedOwnPane(env, backend, instance) {
+  if (backend !== "tmux")
+    return {
+      absent: `the daemon serves the ${backend} backend, and Herdsman drives only tmux`
+    };
+  if (instance === void 0 || instance === "")
+    return {
+      pending: "the daemon did not name the tmux server it addresses"
+    };
+  const server = tmuxServerName(env);
+  if (server === void 0)
+    return {
+      absent: "this process's own tmux client names no server, so it is not in the pane it would publish"
+    };
+  if (server !== instance)
+    return {
+      absent: `this process is attached to tmux server ${server}, not to ${instance}`
+    };
+  const pane = radarLocalPane(env);
+  if (pane === void 0)
+    return {
+      absent: "this process's own environment names no tmux pane of that server"
+    };
+  return { pane: `tmux:${instance}:${pane}` };
+}
+function observedContainment(inventory, paneId) {
+  const rows = inventory.panes.filter((pane) => pane.pane_id === paneId);
+  if (rows.length === 0) return void 0;
+  if (rows.length > 1) return { ambiguous: `topology reports pane ${paneId} twice` };
+  const row = rows[0];
+  const tab = inventory.tabs.find((candidate) => candidate.tab_id === row.tab_id);
+  if (tab !== void 0 && tab.workspace_id !== row.workspace_id)
+    return {
+      ambiguous: `pane ${paneId} is reported in ${row.workspace_id}, but its tab belongs to ${tab.workspace_id}`
+    };
+  return { pane: row };
+}
+async function resolveRadarProcessLocation(client, env = process.env) {
+  let ready;
+  try {
+    ready = await client.ping();
+  } catch {
+    return { state: "pending", reason: "the daemon did not answer this process" };
+  }
+  if (ready.ok === false)
+    return {
+      state: "pending",
+      reason: `the daemon did not answer this process (${ready.code})`
+    };
+  const backend = ready.value.backend;
+  if (backend === void 0 || backend === "none")
+    return { state: "absent", reason: "the daemon serves no physical backend" };
+  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;
+  if (paneId === env.PI_HERDSMAN_PARENT_PANE_ID?.trim())
+    return {
+      state: "absent",
+      reason: "this process is in the pane its launch was created beside, not in a pane of its own"
+    };
+  let inventory;
+  try {
+    inventory = await client.observe();
+  } catch {
+    return {
+      state: "pending",
+      reason: "the daemon's topology could not be read for this process's pane"
+    };
+  }
+  if (inventory.ok === false)
+    return {
+      state: "pending",
+      reason: `the daemon's topology could not be read (${inventory.code})`
+    };
+  const containment = observedContainment(inventory.value, paneId);
+  if (containment === void 0)
+    return {
+      state: "pending",
+      reason: `the daemon's topology does not report pane ${paneId} yet`
+    };
+  if ("ambiguous" in containment)
+    return { state: "pending", reason: containment.ambiguous };
+  const row = containment.pane;
+  return {
+    state: "resolved",
+    location: {
+      backend,
+      ...instance !== void 0 ? { instance } : {},
+      workspace: row.workspace_id,
+      tab: row.tab_id,
+      pane: paneId
+    }
+  };
+}
+
+// extension/radar-launch.ts
+function unknownChild(reason) {
+  return { kind: "unknown", diagnostic: trajectory(reason) };
+}
+function trajectory(reason) {
+  return `the daemon's current record of this launch's child is ${reason}`;
+}
+async function observeRadarChild(client, provenance) {
+  if (provenance.registration_id === void 0)
+    return unknownChild("not bound to a child by this launch");
+  if (provenance.pane_id === void 0)
+    return unknownChild("without a pane this launch recorded for it");
+  const read = await client.spawnGet(provenance.request_id);
+  if (read.ok === false)
+    return unknownChild(
+      `not readable (${read.code}: ${read.message})`
+    );
+  const topology = read.value;
+  const edge = topology.edge;
+  if (edge.bound === void 0 || edge.bound.registration_id === void 0)
+    return unknownChild("not bound to a child by the daemon");
+  if (edge.bound.registration_id !== provenance.registration_id)
+    return unknownChild(
+      `bound to another subject (${edge.bound.registration_id}), not to ${provenance.registration_id}`
+    );
+  if (edge.location?.pane === void 0)
+    return unknownChild("recorded without a pane");
+  if (edge.location.pane !== provenance.pane_id)
+    return unknownChild(
+      `recorded on pane ${edge.location.pane}, not on ${provenance.pane_id}`
+    );
+  if (edge.exit_observation?.state !== "unknown")
+    return unknownChild("recorded with an observed process exit");
+  if (topology.freshness !== "fresh")
+    return unknownChild(
+      "on a pane the daemon's own inventory does not currently report"
+    );
+  if (topology.state !== "bound")
+    return unknownChild(
+      `not currently placed (state ${topology.state ?? "unreported"})`
+    );
+  const reply = await client.agentGet(edge.bound.registration_id);
+  if (reply.ok === false)
+    return unknownChild(
+      `process verdict not readable (${reply.code}: ${reply.message})`
+    );
+  const { verification, location, contextSession } = reply.value;
+  if (verification === "absent" || verification === "mismatched")
+    return {
+      kind: "gone",
+      verification,
+      diagnostic: trajectory(`the registered process is ${verification}`)
+    };
+  if (verification !== "verified")
+    return unknownChild(`process verdict is ${verification}`);
+  if (location?.pane !== provenance.pane_id)
+    return unknownChild(
+      `registered on ${location?.pane ?? "no pane"}, not on ${provenance.pane_id}`
+    );
+  if (provenance.session_id === void 0)
+    return unknownChild("without a session this launch recorded for it");
+  if (contextSession !== provenance.session_id)
+    return unknownChild(
+      `publishing session ${contextSession ?? "none"}, not ${provenance.session_id}`
+    );
+  return {
+    kind: "live",
+    evidence: {
+      request_id: provenance.request_id,
+      registration_id: edge.bound.registration_id,
+      source: edge.bound.source,
+      incarnation: edge.bound.incarnation,
+      pane_id: edge.location.pane
+    }
+  };
+}
+
+// extension/radar-children.ts
+var PAGE = 100;
+var MAX_PAGES = 20;
+function createRadarChildren(client, publication) {
+  const held = /* @__PURE__ */ new Map();
+  async function resolveAll() {
+    const newest = /* @__PURE__ */ new Map();
+    let after;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const read = await client.spawnList({ ...after !== void 0 ? { after } : {}, limit: PAGE });
+      if (read.ok === false) return read;
+      for (const edge of read.value.spawns) {
+        const bound = edge.bound;
+        if (!bound?.subject_id || !bound.registration_id || edge.launched !== "completed") continue;
+        const at = Date.parse(bound.bound_at);
+        if (Number.isNaN(at)) continue;
+        const current = newest.get(bound.subject_id);
+        if (current !== void 0 && current.at >= at) continue;
+        newest.set(bound.subject_id, {
+          at,
+          registration_id: bound.registration_id,
+          child: {
+            subject_id: bound.subject_id,
+            request_id: edge.request_id,
+            ...edge.location?.pane ? { pane_id: edge.location.pane } : {},
+            state: edge.state,
+            exited: edge.exit_observation != null && edge.exit_observation.state !== "unknown"
+          }
+        });
+      }
+      if (!read.value.next) return { ok: true, value: newest };
+      after = read.value.next;
+    }
+    return { ok: false, code: "protocol", message: "the caller's launches exceed the readable pages" };
+  }
+  async function resolve2(subject) {
+    const all = await resolveAll();
+    return all.ok ? all.value.get(subject) : void 0;
+  }
+  async function resolveAndFollow(subject) {
+    const all = await resolveAll();
+    if (!all.ok) return void 0;
+    follow(all.value);
+    return all.value.get(subject);
+  }
+  function follow(all) {
+    for (const [subject, entry] of held) {
+      const target = all.get(subject);
+      if (target !== void 0 && entry.published !== target.registration_id)
+        entry.publish?.(target);
+    }
+  }
+  return {
+    async list() {
+      const all = await resolveAll();
+      if (!all.ok) return all;
+      follow(all.value);
+      return { ok: true, value: [...all.value.values()].map((entry) => entry.child) };
+    },
+    assignment(subject, owner) {
+      const existing = held.get(subject);
+      if (existing !== void 0) return existing.writer;
+      let latest;
+      const entry = { writer: void 0 };
+      const send = (target) => {
+        if (latest === void 0) return;
+        if (entry.published !== void 0 && entry.published !== target.registration_id)
+          publication.retireAssignment(entry.published);
+        entry.published = target.registration_id;
+        publication.assignment(target.registration_id, owner).update(latest);
+      };
+      entry.publish = send;
+      entry.writer = {
+        update(snapshot) {
+          latest = snapshot;
+          void resolve2(subject).then((target) => {
+            if (target !== void 0) send(target);
+          });
+        },
+        retire() {
+          latest = void 0;
+          if (entry.published !== void 0) publication.retireAssignment(entry.published);
+          entry.published = void 0;
+        }
+      };
+      held.set(subject, entry);
+      return entry.writer;
+    },
+    retire(subject) {
+      held.get(subject)?.writer.retire();
+      held.delete(subject);
+    },
+    async observe(subject, session_id) {
+      const target = await resolveAndFollow(subject);
+      if (target === void 0)
+        return { kind: "unknown", diagnostic: "the daemon records no bound launch for this child" };
+      return observeRadarChild(client, {
+        request_id: target.child.request_id,
+        pane_id: target.child.pane_id,
+        registration_id: target.registration_id,
+        session_id
+      });
+    },
+    async inspect(subject, session_id) {
+      const target = await resolveAndFollow(subject);
+      if (target?.child.pane_id === void 0)
+        throw new Error("Inspection target is not a bound child with a pane");
+      return inspectRadarChild(client, {
+        agentId: target.registration_id,
+        paneId: target.child.pane_id,
+        ...session_id !== void 0 ? { session: session_id } : {}
+      });
+    }
+  };
+}
+
 // extension/radar-communication.ts
 function createRadarHandoffPort(client, publication, parentSubjectId = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID) {
   async function agentId() {
@@ -1418,7 +1793,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();
@@ -1848,11 +2229,6 @@ 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,
@@ -1891,7 +2267,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(), initial_load: state === void 0, releases };
+      state = { version: 2, session, claim_id: randomUUID2(), releases };
       save();
       stopped = false;
       void ensure();
@@ -1974,8 +2350,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);
@@ -2099,7 +2475,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
@@ -2286,7 +2662,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();
@@ -2449,116 +2825,9 @@ function createRadarExecutionAdapter(pi, options) {
   };
 }
 
-// extension/radar-location.ts
-import { basename } from "node:path";
-function radarLocalPane(env) {
-  const pane = env.TMUX_PANE?.trim();
-  return pane && /^%\d+$/.test(pane) ? pane : void 0;
-}
-function tmuxServerName(env) {
-  const socket = env.TMUX?.trim().split(",")[0];
-  return socket ? basename(socket) || void 0 : void 0;
-}
-function qualifiedOwnPane(env, backend, instance) {
-  if (backend !== "tmux")
-    return {
-      absent: `the daemon serves the ${backend} backend, and Herdsman drives only tmux`
-    };
-  if (instance === void 0 || instance === "")
-    return {
-      pending: "the daemon did not name the tmux server it addresses"
-    };
-  const server = tmuxServerName(env);
-  if (server === void 0)
-    return {
-      absent: "this process's own tmux client names no server, so it is not in the pane it would publish"
-    };
-  if (server !== instance)
-    return {
-      absent: `this process is attached to tmux server ${server}, not to ${instance}`
-    };
-  const pane = radarLocalPane(env);
-  if (pane === void 0)
-    return {
-      absent: "this process's own environment names no tmux pane of that server"
-    };
-  return { pane: `tmux:${instance}:${pane}` };
-}
-function observedContainment(inventory, paneId) {
-  const rows = inventory.panes.filter((pane) => pane.pane_id === paneId);
-  if (rows.length === 0) return void 0;
-  if (rows.length > 1) return { ambiguous: `topology reports pane ${paneId} twice` };
-  const row = rows[0];
-  const tab = inventory.tabs.find((candidate) => candidate.tab_id === row.tab_id);
-  if (tab !== void 0 && tab.workspace_id !== row.workspace_id)
-    return {
-      ambiguous: `pane ${paneId} is reported in ${row.workspace_id}, but its tab belongs to ${tab.workspace_id}`
-    };
-  return { pane: row };
-}
-async function resolveRadarProcessLocation(client, env = process.env) {
-  let ready;
-  try {
-    ready = await client.ping();
-  } catch {
-    return { state: "pending", reason: "the daemon did not answer this process" };
-  }
-  if (ready.ok === false)
-    return {
-      state: "pending",
-      reason: `the daemon did not answer this process (${ready.code})`
-    };
-  const backend = ready.value.backend;
-  if (backend === void 0 || backend === "none")
-    return { state: "absent", reason: "the daemon serves no physical backend" };
-  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;
-  if (paneId === env.PI_HERDSMAN_PARENT_PANE_ID?.trim())
-    return {
-      state: "absent",
-      reason: "this process is in the pane its launch was created beside, not in a pane of its own"
-    };
-  let inventory;
-  try {
-    inventory = await client.observe();
-  } catch {
-    return {
-      state: "pending",
-      reason: "the daemon's topology could not be read for this process's pane"
-    };
-  }
-  if (inventory.ok === false)
-    return {
-      state: "pending",
-      reason: `the daemon's topology could not be read (${inventory.code})`
-    };
-  const containment = observedContainment(inventory.value, paneId);
-  if (containment === void 0)
-    return {
-      state: "pending",
-      reason: `the daemon's topology does not report pane ${paneId} yet`
-    };
-  if ("ambiguous" in containment)
-    return { state: "pending", reason: containment.ambiguous };
-  const row = containment.pane;
-  return {
-    state: "resolved",
-    location: {
-      backend,
-      ...instance !== void 0 ? { instance } : {},
-      workspace: row.workspace_id,
-      tab: row.tab_id,
-      pane: paneId
-    }
-  };
-}
-
 // extension/radar-runtime.ts
 var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-var RADAR_RUNTIME_VERSION = 2;
+var RADAR_RUNTIME_VERSION = 3;
 function lazyRadarRuntime(start) {
   let pending;
   return {
@@ -2587,6 +2856,7 @@ function registerPiRadar(pi) {
   const runtime = lazyRadarRuntime(async () => ({
     publication: execution.publication,
     communication: createRadarHandoffPort(client, execution.publication),
+    children: createRadarChildren(client, execution.publication),
     execution
   }));
   provideRadarRuntime(pi.events, runtime);