@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

package/extensions/dm-lens/dist/clients/instance-registry.js

@@ -0,0 +1,595 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeFileAtomic, writeFileAtomicAsync } from "./atomic-write.js";
+import { incrementDegradationCount, recordDegradationOnce } from "./degradation-ledger.js";
+import { getGlobalDmLensDir } from "./file-utils.js";
+import { createGenerationSource } from "./generation-guard.js";
+import { LOCK_WAIT_THROUGH_LEASE_MS, withInstanceRegistryLock, withInstanceRegistryLockSync } from "./instance-registry-lock.js";
+import { BACKSTOP_SCAN_TIMEOUT_MS, realIsPidAlive, STALE_HEARTBEAT_MS, terminateScannerChild } from "./instance-reaper.js";
+import { normalizeFilePath } from "./path-utils.js";
+import { isInPidNamespace, ownPidNamespace, ownProcessStart, ownProcessStartIfKnown, readProcessStart } from "./process-snapshot.js";
+import { queueRegistryMutation } from "./instance-registry-tail.js";
+import { getProcessSingleton } from "./process-singletons.js";
+import { getSubagentIdentity, isSubagentSession } from "./subagent-mode.js";
+function registryPath() {
+  return path.join(getGlobalDmLensDir(), "instances.json");
+}
+function startReadOptions() {
+  return {
+    timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS,
+    onTimeout: (child) => terminateScannerChild(child, {
+      kind: "orphan-backstop-scanner-escalated",
+      timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS
+    })
+  };
+}
+function isOwnEntry(entry, selfStart) {
+  return entry.pid === process.pid && (entry.processStart === undefined || entry.processStart === selfStart);
+}
+let _enabledCache;
+export function isInstanceRegistryEnabled() {
+  if (_enabledCache !== undefined)
+    return _enabledCache;
+  _enabledCache = process.env.DM_LENS_INSTANCE_REGISTRY !== "0";
+  return _enabledCache;
+}
+export function _resetInstanceRegistryEnabledForTests() {
+  _enabledCache = undefined;
+}
+function recordCorruptRegistryRead(reasonCode) {
+  recordDegradationOnce({
+    kind: "instance-registry-corrupt",
+    subject: "instances.json",
+    reason: `read failed (${reasonCode}); treating as empty`
+  });
+}
+function readRegistrySync() {
+  try {
+    const raw = fs.readFileSync(registryPath(), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.instances)) {
+      return parsed;
+    }
+    recordCorruptRegistryRead("invalid shape");
+    return { instances: [] };
+  } catch (err) {
+    const code = err?.code;
+    if (code !== "ENOENT")
+      recordCorruptRegistryRead(code ?? "invalid");
+    return { instances: [] };
+  }
+}
+async function readRegistryAsync() {
+  try {
+    const raw = await fs.promises.readFile(registryPath(), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.instances)) {
+      return parsed;
+    }
+    recordCorruptRegistryRead("invalid shape");
+    return { instances: [] };
+  } catch (err) {
+    const code = err?.code;
+    if (code !== "ENOENT")
+      recordCorruptRegistryRead(code ?? "invalid");
+    return { instances: [] };
+  }
+}
+export async function readInstanceRegistry() {
+  const file = await readRegistryAsync();
+  return file.instances;
+}
+async function writeRegistryAsync(file) {
+  const dir = getGlobalDmLensDir();
+  const target = registryPath();
+  try {
+    await fs.promises.mkdir(dir, { recursive: true });
+  } catch {
+    return;
+  }
+  await writeFileAtomicAsync(target, JSON.stringify(file));
+}
+const REGISTRY_WRITE_RETRIES = 3;
+async function writeRegistryWithRetry(mutate, isCommitted) {
+  await withInstanceRegistryLock(registryPath(), async () => {
+    for (let attempt = 0;attempt < REGISTRY_WRITE_RETRIES; attempt++) {
+      const next = mutate(await readRegistryAsync());
+      if (next === undefined)
+        return;
+      await writeRegistryAsync(next);
+      if (isCommitted(await readRegistryAsync()))
+        return;
+    }
+  });
+}
+function writeRegistrySync(file) {
+  const dir = getGlobalDmLensDir();
+  const target = registryPath();
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    return;
+  }
+  writeFileAtomic(target, JSON.stringify(file));
+}
+export function getInstanceRoots(entry) {
+  const listed = Array.isArray(entry.projectRoots) ? entry.projectRoots.filter((root) => typeof root === "string" && root.length > 0) : [];
+  if (listed.length > 0)
+    return listed;
+  return typeof entry.projectRoot === "string" && entry.projectRoot.length > 0 ? [entry.projectRoot] : [];
+}
+const INSTANCE_ROOT_CAP = 32;
+export function mergeInstanceRoots(priorRoots, normalizedRoot) {
+  const roots = priorRoots.includes(normalizedRoot) ? [...priorRoots] : [...priorRoots, normalizedRoot];
+  while (roots.length > INSTANCE_ROOT_CAP)
+    roots.splice(1, 1);
+  return roots;
+}
+const HOST_ROOT_HOLDER = "host";
+const ROOT_HOLDER_CAP = 2 * INSTANCE_ROOT_CAP;
+function readRootHolders(entry) {
+  const raw = entry.projectRootHolders;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { [HOST_ROOT_HOLDER]: getInstanceRoots(entry) };
+  }
+  const holders = {};
+  for (const [holder, listed] of Object.entries(raw)) {
+    if (!Array.isArray(listed))
+      continue;
+    holders[holder] = listed.filter((root) => typeof root === "string" && root.length > 0);
+  }
+  return holders;
+}
+function settleRootHolders(roots, holders) {
+  const primary = roots[0];
+  const settled = {};
+  for (const [holder, listed] of Object.entries(holders)) {
+    const kept = roots.filter((root) => listed.includes(root));
+    if (kept.length > 0)
+      settled[holder] = kept;
+  }
+  if (primary !== undefined) {
+    settled[HOST_ROOT_HOLDER] = roots.filter((root) => root === primary || holders[HOST_ROOT_HOLDER]?.includes(root) === true);
+  }
+  const secondaries = Object.keys(settled).filter((holder) => holder !== HOST_ROOT_HOLDER);
+  for (const holder of secondaries.slice(0, Math.max(0, secondaries.length - ROOT_HOLDER_CAP))) {
+    delete settled[holder];
+  }
+  const listed = new Set(Object.values(settled).flat());
+  return { roots: roots.filter((root) => listed.has(root)), holders: settled };
+}
+export function registerInstance(projectRoot) {
+  const generation = registrationGeneration().capture();
+  return queueRegistryMutation(() => registerInstanceNow(projectRoot, generation));
+}
+async function registerInstanceNow(projectRoot, generation) {
+  if (!isInstanceRegistryEnabled())
+    return;
+  const normalizedRoot = normalizeFilePath(projectRoot);
+  if (!registrationIsCurrent(generation, normalizedRoot))
+    return;
+  rememberRegistrationRoot(projectRoot);
+  const pid = process.pid;
+  const now = new Date().toISOString();
+  const identity = isSubagentSession() ? getSubagentIdentity() : undefined;
+  const selfStart = await ownProcessStart(startReadOptions());
+  const subagent = identity ? {
+    marker: identity.marker,
+    agentType: identity.agentName,
+    parentPid: identity.parentPid,
+    runId: identity.runId
+  } : undefined;
+  await writeRegistryWithRetry((file) => {
+    if (!registrationIsCurrent(generation, normalizedRoot))
+      return;
+    const others = file.instances.filter((entry) => !isOwnEntry(entry, selfStart));
+    const existing = file.instances.find((entry) => isOwnEntry(entry, selfStart));
+    const existingRoots = existing ? getInstanceRoots(existing) : [];
+    const roots = existing?.rootSource === "lsp-fallback" ? existingRoots.slice(1).reduce((acc, root) => mergeInstanceRoots(acc, root), [normalizedRoot]) : mergeInstanceRoots(existingRoots, normalizedRoot);
+    const holders = existing ? readRootHolders(existing) : {};
+    const settled = settleRootHolders(roots, {
+      ...holders,
+      [HOST_ROOT_HOLDER]: [
+        ...holders[HOST_ROOT_HOLDER] ?? [],
+        normalizedRoot
+      ]
+    });
+    const namespace = ownPidNamespace();
+    others.push({
+      pid,
+      ...selfStart === undefined ? {} : { processStart: selfStart },
+      ...namespace === undefined ? {} : { pidNamespace: namespace },
+      startedAt: existing?.startedAt ?? now,
+      projectRoot: settled.roots[0] ?? normalizedRoot,
+      projectRoots: settled.roots,
+      projectRootHolders: settled.holders,
+      lspChildren: existing?.lspChildren ?? [],
+      lspChildCount: existing?.lspChildren?.length ?? 0,
+      rssBytes: process.memoryUsage().rss,
+      heartbeatAt: now,
+      ...subagent ? { subagent } : {}
+    });
+    return { instances: others };
+  }, (file) => file.instances.some((entry) => isOwnEntry(entry, selfStart)));
+}
+export function registerInstanceRoot(projectRoot, holder) {
+  return queueRegistryMutation(() => registerInstanceRootNow(projectRoot, holder));
+}
+async function registerInstanceRootNow(projectRoot, holder) {
+  if (!isInstanceRegistryEnabled())
+    return;
+  const normalizedRoot = normalizeFilePath(projectRoot);
+  const selfStart = await ownProcessStart(startReadOptions());
+  await withInstanceRegistryLock(registryPath(), async () => {
+    const file = await readRegistryAsync();
+    const idx = file.instances.findIndex((entry) => isOwnEntry(entry, selfStart));
+    const current = file.instances[idx];
+    if (current === undefined)
+      return;
+    const priorRoots = getInstanceRoots(current);
+    if (priorRoots[0] === normalizedRoot)
+      return;
+    const holders = readRootHolders(current);
+    const settled = settleRootHolders(mergeInstanceRoots(priorRoots, normalizedRoot), {
+      ...holders,
+      [holder]: [...holders[holder] ?? [], normalizedRoot]
+    });
+    if (settled.roots.length === priorRoots.length && settled.roots.every((root, index) => root === priorRoots[index]) && JSON.stringify(settled.holders) === JSON.stringify(current.projectRootHolders))
+      return;
+    file.instances[idx] = {
+      ...current,
+      projectRoot: settled.roots[0] ?? current.projectRoot,
+      projectRoots: settled.roots,
+      projectRootHolders: settled.holders
+    };
+    await writeRegistryAsync(file);
+  });
+}
+export async function updateHeartbeat(patch = {}) {
+  return queueRegistryMutation(() => updateHeartbeatNow(patch));
+}
+async function updateHeartbeatNow(patch) {
+  if (!isInstanceRegistryEnabled())
+    return;
+  const pid = process.pid;
+  const selfStart = await ownProcessStart(startReadOptions());
+  let missing = false;
+  await withInstanceRegistryLock(registryPath(), async () => {
+    const file = await readRegistryAsync();
+    const idx = file.instances.findIndex((entry) => isOwnEntry(entry, selfStart));
+    if (idx === -1) {
+      missing = true;
+      return;
+    }
+    const now = new Date().toISOString();
+    const current = file.instances[idx];
+    const lspChildren = patch.childUsage ? current.lspChildren.map((child) => {
+      const usage = patch.childUsage?.[child.pid];
+      if (!usage)
+        return child;
+      return {
+        ...child,
+        rssBytes: usage.rssBytes ?? child.rssBytes,
+        cpuPercent: usage.cpuPercent ?? child.cpuPercent
+      };
+    }) : current.lspChildren;
+    file.instances[idx] = {
+      ...current,
+      rssBytes: patch.rssBytes ?? process.memoryUsage().rss,
+      cpuPercent: patch.cpuPercent ?? current.cpuPercent,
+      lspChildren,
+      lspChildCount: lspChildren.length,
+      heartbeatAt: now
+    };
+    await writeRegistryAsync(file);
+  });
+  const intent = registrationIntent();
+  if (missing && intent.root !== undefined && intent.target === registryPath()) {
+    incrementDegradationCount({
+      kind: "instance-registry-registration-missing",
+      subject: String(pid),
+      reason: "entry missing at heartbeat; re-registering from the session root"
+    });
+    registerInstance(intent.root);
+  }
+}
+const REGISTRATION_INTENT_FAMILY = "instance-registry.registration-intent";
+const REGISTRATION_INTENT_VERSION = 1;
+function registrationIntent() {
+  return getProcessSingleton(REGISTRATION_INTENT_FAMILY, REGISTRATION_INTENT_VERSION, () => ({ root: undefined, target: undefined }));
+}
+const REGISTRATION_GENERATION_FAMILY = "instance-registry.registration-generation";
+const REGISTRATION_GENERATION_VERSION = 1;
+function registrationGeneration() {
+  return getProcessSingleton(REGISTRATION_GENERATION_FAMILY, REGISTRATION_GENERATION_VERSION, () => createGenerationSource("instance-registry-registration"));
+}
+function registrationIsCurrent(generation, normalizedRoot) {
+  if (generation.isCurrent())
+    return true;
+  incrementDegradationCount({
+    kind: "instance-registry-registration-superseded",
+    subject: normalizedRoot,
+    reason: "the session ended before this registration landed; dropped"
+  });
+  return false;
+}
+function rememberRegistrationRoot(root) {
+  const intent = registrationIntent();
+  intent.root = root;
+  intent.target = root === undefined ? undefined : registryPath();
+}
+export { _settleRegistryMutationsForTests } from "./instance-registry-tail.js";
+export function recordLspChild(entry) {
+  const generation = registrationGeneration().capture();
+  return queueRegistryMutation(() => recordLspChildNow(entry, generation));
+}
+async function recordLspChildNow(entry, generation) {
+  if (!isInstanceRegistryEnabled())
+    return;
+  const pid = process.pid;
+  const now = new Date().toISOString();
+  const [selfStart, childStart] = await Promise.all([
+    ownProcessStart(startReadOptions()),
+    readProcessStart(entry.pid, startReadOptions())
+  ]);
+  const childEntry = {
+    pid: entry.pid,
+    serverId: entry.serverId,
+    command: entry.command,
+    marker: entry.marker,
+    spawnedAt: now,
+    ...childStart === undefined ? {} : { processStart: childStart }
+  };
+  const hostIdentity = getSubagentIdentity();
+  await writeRegistryWithRetry((file) => {
+    const idx = file.instances.findIndex((inst) => isOwnEntry(inst, selfStart));
+    if (idx === -1) {
+      const guessedRoot = normalizeFilePath(entry.sessionIdentity?.projectRoot ?? process.cwd());
+      if (!registrationIsCurrent(generation, guessedRoot))
+        return;
+      recordDegradationOnce({
+        kind: "instance-registry-registration-missing",
+        subject: String(pid),
+        reason: "synthesizing host entry while recording an LSP child"
+      });
+      const identity = entry.sessionIdentity;
+      if (!identity?.projectRoot) {
+        recordDegradationOnce({
+          kind: "instance-registry-identity-fallback",
+          subject: String(pid),
+          reason: "session cwd unavailable; using process cwd"
+        });
+      }
+      const projectRoot = normalizeFilePath(identity?.projectRoot ?? process.cwd());
+      const namespace = ownPidNamespace();
+      file.instances.push({
+        pid,
+        ...selfStart === undefined ? {} : { processStart: selfStart },
+        ...namespace === undefined ? {} : { pidNamespace: namespace },
+        startedAt: identity?.startedAt ?? now,
+        projectRoot,
+        rootSource: identity?.rootSource ?? "lsp-fallback",
+        projectRoots: [projectRoot],
+        lspChildren: [childEntry],
+        lspChildCount: 1,
+        rssBytes: process.memoryUsage().rss,
+        heartbeatAt: now,
+        ...hostIdentity ? {
+          subagent: {
+            marker: hostIdentity.marker,
+            agentType: hostIdentity.agentName,
+            parentPid: hostIdentity.parentPid,
+            runId: hostIdentity.runId
+          }
+        } : {}
+      });
+    } else {
+      const current = file.instances[idx];
+      const filtered = current.lspChildren.filter((child) => child.pid !== entry.pid);
+      filtered.push(childEntry);
+      file.instances[idx] = {
+        ...current,
+        lspChildren: filtered,
+        lspChildCount: filtered.length
+      };
+    }
+    return file;
+  }, (file) => file.instances.some((instance) => isOwnEntry(instance, selfStart) && instance.lspChildren.some((child) => child.pid === entry.pid)));
+}
+export function removeLspChild(pid, expectedMarker) {
+  return queueRegistryMutation(() => removeLspChildNow(pid, expectedMarker));
+}
+async function removeLspChildNow(pid, expectedMarker) {
+  if (!isInstanceRegistryEnabled())
+    return;
+  const selfStart = await ownProcessStart(startReadOptions());
+  await withInstanceRegistryLock(registryPath(), async () => {
+    const file = await readRegistryAsync();
+    const idx = file.instances.findIndex((inst) => isOwnEntry(inst, selfStart));
+    if (idx === -1)
+      return;
+    const current = file.instances[idx];
+    const filtered = current.lspChildren.filter((child) => {
+      if (child.pid !== pid)
+        return true;
+      if (expectedMarker && child.marker && child.marker !== expectedMarker) {
+        return true;
+      }
+      return false;
+    });
+    if (filtered.length === current.lspChildren.length)
+      return;
+    file.instances[idx] = {
+      ...current,
+      lspChildren: filtered,
+      lspChildCount: filtered.length
+    };
+    await writeRegistryAsync(file);
+  });
+}
+export function deregisterInstance() {
+  rememberRegistrationRoot(undefined);
+  registrationGeneration().bump();
+  if (!isInstanceRegistryEnabled())
+    return;
+  const selfStart = ownProcessStartIfKnown();
+  const removed = withInstanceRegistryLockSync(registryPath(), () => {
+    const next = withoutOwnEntry(readRegistrySync(), selfStart);
+    if (next)
+      writeRegistrySync(next);
+    return true;
+  });
+  if (removed)
+    return;
+  incrementDegradationCount({
+    kind: "instance-registry-deregister-queued",
+    subject: String(process.pid),
+    reason: "the sync removal could not take the registry lock; queued behind the holder"
+  });
+  queueRegistryMutation(deregisterInstanceAfterHolder);
+}
+async function deregisterInstanceAfterHolder() {
+  const selfStart = await ownProcessStart(startReadOptions());
+  await withInstanceRegistryLock(registryPath(), async () => {
+    const next = withoutOwnEntry(await readRegistryAsync(), selfStart);
+    if (next)
+      await writeRegistryAsync(next);
+    incrementDegradationCount({
+      kind: "instance-registry-deregister-landed",
+      subject: String(process.pid),
+      reason: next ? "the queued removal took the lock and removed this process's entry" : "the queued removal took the lock; the entry was already gone"
+    });
+  }, LOCK_WAIT_THROUGH_LEASE_MS);
+}
+function withoutOwnEntry(file, selfStart) {
+  const remaining = file.instances.filter((entry) => !isOwnEntry(entry, selfStart));
+  return remaining.length === file.instances.length ? undefined : { instances: remaining };
+}
+export function deregisterInstanceRoot(projectRoot, holder) {
+  const generation = registrationGeneration().capture();
+  return queueRegistryMutation(async () => deregisterInstanceRootNow(projectRoot, holder, generation));
+}
+const ROOT_REMOVAL_REASONS = {
+  kept: "holder left; another holder keeps the root",
+  freed: "last holder left; root freed",
+  none: "the queued removal took the lock; there was nothing left to remove"
+};
+function planRootRemoval(file, normalizedRoot, holder, selfStart, generation) {
+  const idx = file.instances.findIndex((entry) => isOwnEntry(entry, selfStart));
+  const current = file.instances[idx];
+  if (current === undefined) {
+    const intent = registrationIntent();
+    if (intent.root !== undefined && normalizeFilePath(intent.root) === normalizedRoot)
+      rememberRegistrationRoot(undefined);
+    return;
+  }
+  const prior = settleRootHolders(getInstanceRoots(current), readRootHolders(current));
+  const held = prior.holders[holder];
+  if (!held?.includes(normalizedRoot))
+    return;
+  const next = settleRootHolders(prior.roots, {
+    ...prior.holders,
+    [holder]: held.filter((root) => root !== normalizedRoot)
+  });
+  if (generation.isCurrent())
+    rememberRegistrationRoot(next.roots[0]);
+  return {
+    file: {
+      instances: file.instances.map((entry, i) => i === idx ? {
+        ...current,
+        projectRoot: next.roots[0] ?? current.projectRoot,
+        projectRoots: next.roots,
+        projectRootHolders: next.holders
+      } : entry)
+    },
+    outcome: next.roots.includes(normalizedRoot) ? "kept" : "freed"
+  };
+}
+async function deregisterInstanceRootNow(projectRoot, holder, generation) {
+  if (!isInstanceRegistryEnabled())
+    return;
+  const normalizedRoot = normalizeFilePath(projectRoot);
+  const selfStart = await ownProcessStart(startReadOptions());
+  await withInstanceRegistryLock(registryPath(), async () => {
+    const next = planRootRemoval(await readRegistryAsync(), normalizedRoot, holder, selfStart, generation);
+    if (next)
+      await writeRegistryAsync(next.file);
+    incrementDegradationCount({
+      kind: "instance-registry-deregister-landed",
+      subject: String(process.pid),
+      reason: ROOT_REMOVAL_REASONS[next?.outcome ?? "none"]
+    });
+  }, LOCK_WAIT_THROUGH_LEASE_MS);
+}
+function rootsOverlap(a, b) {
+  if (a === b)
+    return true;
+  const [shorter, longer] = a.length < b.length ? [a, b] : [b, a];
+  return longer.startsWith(shorter.endsWith("/") ? shorter : `${shorter}/`);
+}
+export function selectLivePeerInstances(entries, root, now = Date.now(), isPidAlive = realIsPidAlive, match = "exact") {
+  const normalizedRoot = normalizeFilePath(root);
+  return entries.filter((entry) => entry.pid !== process.pid && getInstanceRoots(entry).some((entryRoot) => match === "exact" ? entryRoot === normalizedRoot : rootsOverlap(entryRoot, normalizedRoot)) && isPidAlive(entry.pid) && Number.isFinite(Date.parse(entry.heartbeatAt)) && now - Date.parse(entry.heartbeatAt) <= STALE_HEARTBEAT_MS).sort((a, b) => Date.parse(a.startedAt) - Date.parse(b.startedAt));
+}
+export function computeResourceFootprint(instances, isPidAlive) {
+  const liveInstances = isPidAlive ? instances.filter((instance) => isPidAlive(instance.pid)) : instances;
+  const perInstance = liveInstances.map((instance) => {
+    const lspChildRssBytes = instance.lspChildren.reduce((sum, child) => sum + (child.rssBytes ?? 0), 0);
+    const lspChildCpuPercent = instance.lspChildren.reduce((sum, child) => sum + (child.cpuPercent ?? 0), 0);
+    const roots = getInstanceRoots(instance);
+    return {
+      pid: instance.pid,
+      projectRoot: roots[0] ?? instance.projectRoot,
+      projectRoots: roots,
+      rssBytes: instance.rssBytes ?? 0,
+      cpuPercent: instance.cpuPercent ?? 0,
+      lspChildCount: instance.lspChildren.length,
+      lspChildRssBytes,
+      lspChildCpuPercent
+    };
+  });
+  let totalRssBytes = 0;
+  let totalCpuPercent = 0;
+  let totalLspChildCount = 0;
+  for (const inst of perInstance) {
+    totalRssBytes += inst.rssBytes + inst.lspChildRssBytes;
+    totalCpuPercent += inst.cpuPercent + inst.lspChildCpuPercent;
+    totalLspChildCount += inst.lspChildCount;
+  }
+  return {
+    instanceCount: perInstance.length,
+    totalRssBytes,
+    totalCpuPercent,
+    totalLspChildCount,
+    perInstance
+  };
+}
+export async function getResourceFootprint(isPidAlive = realIsPidAlive) {
+  const instances = await readInstanceRegistry();
+  const namespace = ownPidNamespace();
+  const dead = instances.filter((instance) => !isPidAlive(instance.pid) && instance.lspChildren.length === 0 && isInPidNamespace(instance, namespace)).map((instance) => ({
+    pid: instance.pid,
+    processStart: instance.processStart,
+    pidNamespace: instance.pidNamespace
+  }));
+  if (dead.length > 0) {
+    queueRegistryMutation(() => prunePids(dead)).catch(() => {});
+  }
+  return computeResourceFootprint(instances, isPidAlive);
+}
+export async function pruneDeadInstances(dead) {
+  const result = await withInstanceRegistryLock(registryPath(), async () => {
+    const file = await readRegistryAsync();
+    const key = (identity) => `${identity.pid}:${identity.processStart ?? ""}:${identity.pidNamespace ?? ""}`;
+    const targets = new Set(dead.map(key));
+    const remaining = file.instances.filter((entry) => !targets.has(key(entry)));
+    if (remaining.length === file.instances.length)
+      return "no-match";
+    await writeRegistryAsync({ instances: remaining });
+    return "pruned";
+  });
+  return result ?? "could-not-acquire";
+}
+async function prunePids(dead) {
+  await pruneDeadInstances(dead);
+}

package/extensions/dm-lens/dist/clients/io-bridge-contract.js

@@ -0,0 +1,7 @@
+import { getProcessBridge } from "./process-bridge.js";
+export const IO_BRIDGE_SYMBOL = Symbol.for("dm-lens:io-bridge");
+export const IO_BRIDGE_VERSION = 2;
+export function getIOBridge() {
+  const candidate = getProcessBridge(IO_BRIDGE_SYMBOL, 2);
+  return typeof candidate?.record === "function" ? candidate : undefined;
+}