pi-radar 0.9.0 → 0.10.0

package/dist/index.js

@@ -9,6 +9,7 @@ var radar_children_exports = {};
 __export(radar_children_exports, {
   createRadarChildren: () => createRadarChildren
 });
+import { randomUUID as randomUUID2 } from "node:crypto";
 
 // extension/radar-inspection.ts
 var radar_inspection_exports = {};
@@ -60,10 +61,12 @@ function utf8Tail(value, maxBytes) {
 // extension/radar-launch.ts
 var radar_launch_exports = {};
 __export(radar_launch_exports, {
+  launchFailure: () => launchFailure,
   launchRadarWorker: () => launchRadarWorker,
   observeRadarChild: () => observeRadarChild,
   readProcessGone: () => readProcessGone,
-  relaunchRefusalForChild: () => relaunchRefusalForChild
+  relaunchRefusalForChild: () => relaunchRefusalForChild,
+  waitForChild: () => waitForChild
 });
 import { setTimeout as delay } from "node:timers/promises";
 
@@ -104,7 +107,7 @@ import { lstatSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 var RADAR_PROTOCOL_VERSION = 2;
-var RADAR_MINIMUM_REVISION = 7;
+var RADAR_MINIMUM_REVISION = 8;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";
@@ -418,6 +421,9 @@ function spawnEdge(value) {
   const agentId = stringAt(bound, "registration_id");
   const subjectId = stringAt(bound, "subject_id");
   const exit = exitAt(recordAt(value, "exit_observation"));
+  const withdrawnRecord = recordAt(value, "withdrawn");
+  const withdrawnAt = stringAt(withdrawnRecord, "at");
+  const withdrawnReason = stringAt(withdrawnRecord, "reason");
   return {
     ok: true,
     value: {
@@ -434,7 +440,9 @@ function spawnEdge(value) {
           ...isUuid(subjectId) ? { subject_id: subjectId } : {}
         }
       } : {},
-      ...exit !== void 0 ? { exit_observation: exit } : {}
+      ...exit !== void 0 ? { exit_observation: exit } : {},
+      ...stringAt(value, "granted_at") !== void 0 ? { granted_at: stringAt(value, "granted_at") } : {},
+      ...withdrawnAt !== void 0 && withdrawnReason !== void 0 ? { withdrawn: { at: withdrawnAt, reason: withdrawnReason } } : {}
     }
   };
 }
@@ -1024,7 +1032,11 @@ function createRadarClient(options = {}) {
           request.request_id
         );
         if (answer.ok === false) return answer;
-        return focusOutcome(recordAt(answer.value, "request"), request.request_id);
+        const settled = focusOutcome(recordAt(answer.value, "request"), request.request_id);
+        if (settled.ok === false) return settled;
+        const launch = recordAt(recordAt(answer.value, "request"), "launch_request_id");
+        if (!isUuid(launch)) return protocol("lifecycle.restart reply names no launch");
+        return { ok: true, value: { ...settled.value, launch_request_id: launch } };
       });
     },
     async spawnList(request) {
@@ -1394,123 +1406,6 @@ function boundedRadarSnapshot(snapshot) {
   };
 }
 
-// extension/radar-location.ts
-var radar_location_exports = {};
-__export(radar_location_exports, {
-  radarLocalPane: () => radarLocalPane,
-  radarPaneHandle: () => radarPaneHandle,
-  resolveRadarProcessLocation: () => resolveRadarProcessLocation,
-  tmuxServerName: () => tmuxServerName
-});
-import { basename } from "node:path";
-function radarLocalPane(env) {
-  const pane = env.TMUX_PANE?.trim();
-  return pane && /^%\d+$/.test(pane) ? pane : void 0;
-}
-function radarPaneHandle(qualified) {
-  return qualified.slice(qualified.lastIndexOf(":") + 1);
-}
-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) };
@@ -1602,7 +1497,7 @@ async function relaunchRefusalForChild(client, agentId) {
   return `the child's registered process is ${verification === "verified" ? "still running" : "not proved gone"}`;
 }
 function refusedLaunch(message) {
-  return { kind: "refused", message };
+  return { kind: "failed", message };
 }
 function unresolvedLaunch(requestId, message) {
   return {
@@ -1611,14 +1506,6 @@ function unresolvedLaunch(requestId, message) {
     message: `spawn ${requestId} is unresolved (${message})`
   };
 }
-function edgeStanding(edge) {
-  if (edge.created === "refused" || edge.launched === "refused")
-    return "refused";
-  return edge.created === "completed" && edge.launched === "completed" ? "launched" : "unknown";
-}
-function edgeMessage(edge) {
-  return `the daemon's spawn record is created ${edge.created} and launched ${edge.launched}`;
-}
 var PRE_EFFECT_CODES = [
   "absent",
   "unsupported",
@@ -1631,14 +1518,12 @@ var PRE_EFFECT_CODES = [
   "busy",
   "backend_unavailable"
 ];
-function spawnFailure(result, requestId) {
+function launchFailure(result, requestId) {
   return PRE_EFFECT_CODES.includes(result.code) ? refusedLaunch(result.message) : unresolvedLaunch(requestId, result.message);
 }
 async function launchRadarWorker(options) {
   const { client, launch, signal } = options;
   const pollMs = options.pollMs ?? 250;
-  const deadline = Date.now() + options.timeoutMs;
-  const remaining = () => Math.max(0, deadline - Date.now());
   const parent = await options.publication.subject();
   if (parent === void 0 || !isUuid(parent.registration_id))
     return refusedLaunch(
@@ -1669,55 +1554,22 @@ async function launchRadarWorker(options) {
     ...Object.keys(launch.env).length > 0 ? { env: launch.env } : {}
   });
   if (spawned.ok === false) {
-    const refusal = spawnFailure(spawned, launch.request_id);
-    if (refusal.kind === "refused") return refusal;
-  }
-  if (spawned.ok === true) {
-    const standing = edgeStanding(spawned.value);
-    if (standing === "refused")
-      return refusedLaunch(edgeMessage(spawned.value));
-    if (standing === "unknown")
-      return unresolvedLaunch(launch.request_id, edgeMessage(spawned.value));
+    const refusal = launchFailure(spawned, launch.request_id);
+    if (refusal.kind === "failed") return refusal;
   }
   const bound = await waitForChild(client, launch.request_id, {
-    remaining,
     pollMs,
     ...signal !== void 0 ? { signal } : {}
   });
   if (bound.kind !== "bound") return bound;
-  const agentId = bound.registration_id;
-  try {
-    const state = await options.readers.waitForState(
-      launch.mailbox,
-      (candidate) => options.readers.startupAckMatches(candidate, {
-        generation: launch.generation,
-        runId: launch.identity.runId,
-        ownerSessionId: launch.identity.ownerSessionId,
-        workspaceId: launch.identity.workspaceId,
-        agentLabel: launch.identity.agentLabel,
-        // The child writes the raw TMUX_PANE of the pane it runs in. Requiring
-        // the pane the daemon created is what refuses a child that inherited
-        // another process's coordinates.
-        paneId: radarPaneHandle(bound.pane_id)
-      }),
-      { timeoutMs: remaining(), ...signal !== void 0 ? { signal } : {} }
-    );
-    return {
-      kind: "ready",
-      value: {
-        request_id: launch.request_id,
-        subject_id: bound.subject_id,
-        pane_id: bound.pane_id,
-        state
-      }
-    };
-  } catch (error) {
-    const claimed = options.readers.readState(launch.mailbox)?.paneId;
-    return unresolvedLaunch(
-      launch.request_id,
-      claimed !== void 0 && claimed !== radarPaneHandle(bound.pane_id) ? `the bound child ${agentId} claims the pane ${claimed}, not the pane ${bound.pane_id} this launch created for it` : `the bound child ${agentId} has not acknowledged this launch's startup (${String(error)})`
-    );
-  }
+  return {
+    kind: "ready",
+    value: {
+      request_id: launch.request_id,
+      subject_id: bound.subject_id,
+      pane_id: bound.pane_id
+    }
+  };
 }
 async function waitForChild(client, requestId, options) {
   let last = "the daemon has not answered";
@@ -1726,37 +1578,21 @@ async function waitForChild(client, requestId, options) {
       return unresolvedLaunch(requestId, `the launch was cancelled (${last})`);
     const answer = await client.spawnGet(requestId);
     if (answer.ok === true) {
-      const { edge, state, freshness } = answer.value;
-      const standing = edgeStanding(edge);
-      if (standing === "refused")
-        return refusedLaunch(`${edgeMessage(edge)}`);
-      if (standing === "unknown")
-        return unresolvedLaunch(requestId, edgeMessage(edge));
+      const { edge } = answer.value;
+      if (edge.withdrawn !== void 0)
+        return refusedLaunch(`the daemon withdrew this launch: ${edge.withdrawn.reason}`);
+      if (edge.granted_at === void 0) {
+        await delay(options.pollMs);
+        continue;
+      }
       const pane = edge.location?.pane;
       if (pane === void 0 || pane === "")
         return unresolvedLaunch(
           requestId,
           "the daemon's launch recorded no pane to verify the child against"
         );
-      if (freshness !== "fresh")
-        return unresolvedLaunch(
-          requestId,
-          state === "unresolved" ? `the daemon's inventory does not report the pane ${pane} its own record names for this child` : `the daemon cannot confirm the pane ${pane} it recorded for this child`
-        );
-      if (edge.exit_observation?.state === "exited")
-        return unresolvedLaunch(
-          requestId,
-          "the daemon observed the launched child's process exit"
-        );
       const agentId = edge.bound?.registration_id;
       if (agentId !== void 0 && isUuid(agentId)) {
-        const source = edge.bound?.source;
-        const incarnation = edge.bound?.incarnation;
-        if (source === void 0 || source === "" || incarnation === void 0 || incarnation === "")
-          return unresolvedLaunch(
-            requestId,
-            `the daemon bound the child ${agentId} without recording the process it registered as`
-          );
         const subjectId = edge.bound?.subject_id;
         if (subjectId === void 0 || !isUuid(subjectId))
           return unresolvedLaunch(
@@ -1766,21 +1602,14 @@ async function waitForChild(client, requestId, options) {
         return {
           kind: "bound",
           subject_id: subjectId,
-          registration_id: agentId,
-          pane_id: pane,
-          source,
-          incarnation
+          pane_id: pane
         };
       }
       last = "no child has registered with this launch's token yet";
     } else {
-      last = answer.message;
+      return unresolvedLaunch(requestId, answer.message);
     }
-    if (options.remaining() <= 0)
-      return unresolvedLaunch(requestId, last);
-    await delay(options.pollMs, void 0, {
-      ...options.signal !== void 0 ? { signal: options.signal } : {}
-    });
+    await delay(options.pollMs);
   }
 }
 
@@ -1797,7 +1626,7 @@ function createRadarChildren(client, publication) {
       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;
+        if (!bound?.subject_id || !bound.registration_id || edge.granted_at == null || edge.withdrawn != null) continue;
         const at = Date.parse(bound.bound_at);
         if (Number.isNaN(at)) continue;
         const current = newest.get(bound.subject_id);
@@ -1843,6 +1672,34 @@ function createRadarChildren(client, publication) {
       follow(all.value);
       return { ok: true, value: [...all.value.values()].map((entry) => entry.child) };
     },
+    async restart(subject, program, options) {
+      const parent = await publication.subject();
+      if (parent?.subject_id === void 0)
+        return { kind: "failed", message: "this process has no Radar registration to restart a child under" };
+      const request_id = randomUUID2();
+      const requested = await client.restart({
+        request_id,
+        parent: parent.registration_id,
+        subject_id: subject,
+        ...program
+      });
+      if (requested.ok === false)
+        return launchFailure(requested, request_id);
+      const bound = await waitForChild(client, requested.value.launch_request_id, {
+        pollMs: options?.pollMs ?? 250,
+        ...options?.signal !== void 0 ? { signal: options.signal } : {}
+      });
+      if (bound.kind !== "bound") return bound;
+      await resolveAndFollow(subject);
+      return {
+        kind: "ready",
+        value: {
+          request_id: requested.value.launch_request_id,
+          subject_id: bound.subject_id,
+          pane_id: bound.pane_id
+        }
+      };
+    },
     assignment(subject, owner) {
       const existing = held.get(subject);
       if (existing !== void 0) return existing.writer;
@@ -1964,7 +1821,7 @@ __export(radar_publication_exports, {
   radarProcessSlot: () => radarProcessSlot,
   readProcessBirth: () => readProcessBirth
 });
-import { createHash, randomUUID as randomUUID2 } from "node:crypto";
+import { createHash, randomUUID as randomUUID3 } from "node:crypto";
 import {
   closeSync,
   constants,
@@ -2094,7 +1951,7 @@ function createPublicationStore(root) {
       ensureDirectory(directory);
       const temporary = join2(
         directory,
-        `.${name.slice(name.lastIndexOf("/") + 1)}.${randomUUID2()}.tmp`
+        `.${name.slice(name.lastIndexOf("/") + 1)}.${randomUUID3()}.tmp`
       );
       const bytes = Buffer.from(JSON.stringify(value), "utf8");
       if (bytes.length > MAX_RECORD_BYTES)
@@ -2150,7 +2007,7 @@ function radarProcessSlot() {
   return host[PROCESS_SLOT];
 }
 function radarProcessIncarnation(slot = radarProcessSlot()) {
-  return slot.incarnation ??= randomUUID2();
+  return slot.incarnation ??= randomUUID3();
 }
 function radarBindingKey(run, owner, label) {
   return createHash("sha256").update(`${run}\0${owner}\0${label}`).digest("hex").slice(0, 32);
@@ -2618,7 +2475,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: randomUUID3(), releases };
       save();
       stopped = false;
       void ensure();
@@ -2655,7 +2512,7 @@ var STORE_IDENTITY = /* @__PURE__ */ new WeakMap();
 function storeIdentity(store) {
   const known = STORE_IDENTITY.get(store);
   if (known !== void 0) return known;
-  const created = randomUUID2();
+  const created = randomUUID3();
   STORE_IDENTITY.set(store, created);
   return created;
 }
@@ -3182,6 +3039,123 @@ function createRadarExecutionAdapter(pi, options) {
   };
 }
 
+// extension/radar-location.ts
+var radar_location_exports = {};
+__export(radar_location_exports, {
+  radarLocalPane: () => radarLocalPane,
+  radarPaneHandle: () => radarPaneHandle,
+  resolveRadarProcessLocation: () => resolveRadarProcessLocation,
+  tmuxServerName: () => tmuxServerName
+});
+import { basename } from "node:path";
+function radarLocalPane(env) {
+  const pane = env.TMUX_PANE?.trim();
+  return pane && /^%\d+$/.test(pane) ? pane : void 0;
+}
+function radarPaneHandle(qualified) {
+  return qualified.slice(qualified.lastIndexOf(":") + 1);
+}
+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_exports = {};
 __export(radar_runtime_exports, {
@@ -3192,7 +3166,7 @@ __export(radar_runtime_exports, {
   requestRadarRuntime: () => requestRadarRuntime
 });
 var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-var RADAR_RUNTIME_VERSION = 3;
+var RADAR_RUNTIME_VERSION = 4;
 function lazyRadarRuntime(start) {
   let pending;
   return {

package/extension/generated-contracts.ts

@@ -911,7 +911,6 @@ export interface ManagedSubject {
   session: string | null;
   state: State;
   subject_id: string;
-  successor: string | null;
 }
 /**
  * Exact spawn-edge child identity required by `spawn.close`.
@@ -1323,7 +1322,6 @@ export interface LifecycleObservation {
   session: string | null;
   state: State;
   subject_id: string;
-  successor: string | null;
 }
 /**
  * A runtime pane: location plus optional display text.
@@ -1452,6 +1450,7 @@ export interface SpawnListPageSerializePublicSpawnTopology {
    * nothing to verify.
    */
   freshness?: SpawnListPageSerializeFreshness | null;
+  granted_at?: string | null;
   launched: SpawnListPageSerializeRequestOutcome;
   location?: SpawnListPageSerializeRegistryLocation | null;
   parent: string;
@@ -1461,6 +1460,7 @@ export interface SpawnListPageSerializePublicSpawnTopology {
   request_id: string;
   state: SpawnListPageSerializeSpawnState;
   version: number;
+  withdrawn?: SpawnListPageSerializeWithdrawn | null;
 }
 /**
  * The child a token bound: the registering incarnation's own registry identity.
@@ -1497,3 +1497,11 @@ export interface SpawnListPageSerializeRegistryLocation {
   tab?: string | null;
   workspace?: string | null;
 }
+/**
+ * Why and when a launch ended without ever presenting, so a reader never infers
+ * failure from absence.
+ */
+export interface SpawnListPageSerializeWithdrawn {
+  at: string;
+  reason: string;
+}