pi-better-harness 0.3.0 → 0.3.2

package/node_modules/pi-better-goal/src/index.ts

@@ -162,6 +162,7 @@ function formatSnapshot(snapshot: ActivitySnapshot): string {
 
 export default function (pi: ExtensionAPI): void {
   const providers = new Map<string, BackgroundActivityProvider>();
+  const providerUnsubscribers = new Map<string, () => void>();
   providers.set("subagents", {
     id: "subagents",
     label: "Subagents",
@@ -172,6 +173,7 @@ export default function (pi: ExtensionAPI): void {
   let foregroundRunning = false;
   let pollTimer: ReturnType<typeof setInterval> | undefined;
   let collecting = false;
+  let collectionPending = false;
   let latestSnapshot: ActivitySnapshot | null = null;
   let backgroundDrainTracker: BackgroundDrainTracker | null = null;
   let lastWakeSignature = "";
@@ -230,6 +232,7 @@ export default function (pi: ExtensionAPI): void {
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
     clearIdleContinuation();
+    syncPollingState();
     // Force a full redraw when the dock height changes (absent ↔ visible clock).
     refreshGoalWidget?.(!wasVisible || !isGoalClockVisible(goal));
   };
@@ -241,6 +244,7 @@ export default function (pi: ExtensionAPI): void {
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
     clearIdleContinuation();
+    syncPollingState();
     refreshGoalWidget?.(wasVisible);
   };
 
@@ -409,12 +413,22 @@ export default function (pi: ExtensionAPI): void {
 
   const collectIfPossible = (): void => {
     const ctx = currentCtx;
-    if (!ctx || collecting) {
+    if (!ctx) {
+      return;
+    }
+    if (collecting) {
+      collectionPending = true;
       return;
     }
     collecting = true;
     void publishSnapshot(ctx).finally(() => {
       collecting = false;
+      if (collectionPending) {
+        collectionPending = false;
+        collectIfPossible();
+      } else {
+        syncPollingState();
+      }
     });
   };
 
@@ -424,7 +438,6 @@ export default function (pi: ExtensionAPI): void {
     }
     pollTimer = setInterval(collectIfPossible, POLL_INTERVAL_MS);
     pollTimer.unref?.();
-    collectIfPossible();
   };
 
   const stopPolling = (): void => {
@@ -435,6 +448,16 @@ export default function (pi: ExtensionAPI): void {
     pollTimer = undefined;
   };
 
+  const syncPollingState = (): void => {
+    const ctx = currentCtx;
+    const goal = ctx ? currentGoalSnapshot(ctx) : null;
+    if (ctx && (isPokeable(goal) || latestSnapshot?.backgroundRunning === true)) {
+      startPolling();
+    } else {
+      stopPolling();
+    }
+  };
+
   const installGoalWidget = (ctx: ExtensionContext): void => {
     if (!ctx.hasUI) {
       return;
@@ -494,8 +517,14 @@ export default function (pi: ExtensionAPI): void {
     if (!candidate || typeof candidate.id !== "string" || typeof candidate.getActivity !== "function") {
       return;
     }
-    providers.set(candidate.id, candidate as BackgroundActivityProvider);
-    collectIfPossible();
+    const accepted = candidate as BackgroundActivityProvider;
+    providerUnsubscribers.get(accepted.id)?.();
+    providerUnsubscribers.delete(accepted.id);
+    providers.set(accepted.id, accepted);
+    if (typeof accepted.onActivityChanged === "function") {
+      providerUnsubscribers.set(accepted.id, accepted.onActivityChanged(collectIfPossible));
+    }
+    if (latestSnapshot) collectIfPossible();
   });
 
   pi.registerCommand("goal", {
@@ -661,7 +690,8 @@ export default function (pi: ExtensionAPI): void {
     foregroundRunning = !ctx.isIdle();
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
     installGoalWidget(ctx);
-    startPolling();
+    latestSnapshot = await publishSnapshot(ctx);
+    syncPollingState();
   });
 
   pi.on("input", async (event, ctx) => {
@@ -762,6 +792,8 @@ export default function (pi: ExtensionAPI): void {
     foregroundRunning = false;
     clearIdleContinuation();
     currentCtx = undefined;
+    latestSnapshot = null;
+    collectionPending = false;
     try {
       ctx.ui.setStatus(EXTENSION_NAME, undefined);
       ctx.ui.setWidget(EXTENSION_NAME, undefined);

package/node_modules/pi-better-goal/src/subagents.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -82,6 +82,46 @@ export function readSubagentMetas(baseDir = defaultSubagentBaseDir()): SubagentR
   return metas.sort((left, right) => right.startedAt - left.startedAt);
 }
 
+export function readParentSubagentMetas(
+  baseDir = defaultSubagentBaseDir(),
+  parentPid = process.pid,
+): SubagentRunMeta[] {
+  const directory = join(baseDir, "by-parent", String(parentPid));
+  ensureParentIndex(baseDir, directory, parentPid);
+  let ids: string[];
+  try {
+    ids = readdirSync(directory).filter((id) => id !== ".initialized");
+  } catch {
+    return [];
+  }
+  return ids
+    .map((id) => readSubagentMeta(baseDir, id))
+    .filter((meta): meta is SubagentRunMeta => meta !== undefined && meta.spawnPid === parentPid)
+    .sort((left, right) => right.startedAt - left.startedAt);
+}
+
+function readSubagentMeta(baseDir: string, id: string): SubagentRunMeta | undefined {
+  try {
+    const meta = JSON.parse(readFileSync(join(baseDir, "runs", id, "meta.json"), "utf8")) as SubagentRunMeta;
+    return typeof meta.id === "string" && typeof meta.status === "string" ? meta : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function ensureParentIndex(baseDir: string, directory: string, parentPid: number): void {
+  try {
+    readFileSync(join(directory, ".initialized"));
+    return;
+  } catch {
+    // Existing registries are backfilled once for this parent process.
+  }
+  const owned = readSubagentMetas(baseDir).filter((meta) => meta.spawnPid === parentPid);
+  mkdirSync(directory, { recursive: true });
+  for (const meta of owned) writeFileSync(join(directory, meta.id), "");
+  writeFileSync(join(directory, ".initialized"), "1");
+}
+
 export function subagentStatusToItem(
   meta: SubagentRunMeta,
   status: SubagentEffectiveStatus,
@@ -122,9 +162,7 @@ export function collectSubagentActivity(
 ): BackgroundProviderSnapshot {
   const parentPid = options.parentPid ?? process.pid;
   const processExists = options.processExists ?? defaultProcessExists;
-  const metas = readSubagentMetas(options.baseDir).filter((meta) =>
-    isCurrentParentSubagent(meta, parentPid),
-  );
+  const metas = readParentSubagentMetas(options.baseDir, parentPid);
 
   return {
     providerId: "subagents",

package/node_modules/pi-better-goal/src/types.ts

@@ -47,6 +47,7 @@ export interface BackgroundActivityProvider {
   id: string;
   label?: string;
   getActivity(ctx: ExtensionContext): BackgroundProviderSnapshot | Promise<BackgroundProviderSnapshot>;
+  onActivityChanged?(notify: () => void): () => void;
 }
 
 export interface ActivitySnapshot {

package/node_modules/pi-better-subagents/cleanup.ts

@@ -13,6 +13,7 @@ import {
     listMetas,
     ownedByThisParent,
     readMeta,
+    removeMetaArtifacts,
     runDir,
     sessionsDir,
     type RunMeta,
@@ -190,7 +191,8 @@ function cleanRunDirs(cutoff: number, errors: string[]): number {
         if (meta) {
             if (!TERMINAL_CLEANUP_STATUSES.has(meta.status)) continue;
             if (terminalTimestamp(meta) >= cutoff) continue;
-            if (removePath(dir, errors)) removed += 1;
+            if (removeMetaArtifacts(meta)) removed += 1;
+            else errors.push(`${dir}: could not remove run artifacts`);
             continue;
         }
 
@@ -379,7 +381,9 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
     const plan = planRegistrySizeCap(collectSizeCapEntries(), { maxBytes, protectedIds });
     const removed: string[] = [];
     for (const id of plan.remove) {
-        if (removePath(runDir(id), errors)) removed.push(id);
+        const meta = readMeta(id);
+        if (meta ? removeMetaArtifacts(meta) : removePath(runDir(id), errors)) removed.push(id);
+        else if (meta) errors.push(`${runDir(id)}: could not remove run artifacts`);
     }
 
     try {

package/node_modules/pi-better-subagents/index.ts

@@ -49,6 +49,9 @@ import {
     writeMeta,
     readMeta,
     listMetas,
+    listActiveMetasForParent,
+    listMetasForOrigin,
+    listMetasForParent,
     onMetaChanged,
     effectiveStatus,
     ownedByThisParent,
@@ -124,6 +127,44 @@ const SUBAGENT_TOOLS = [
     "subagent_result",
 ];
 
+const GOAL_READY_EVENT = "pi-better-goal:ready";
+const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
+const goalReadySubscriptions = new WeakSet<ExtensionAPI>();
+
+function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
+    const emitProvider = (): void => {
+        pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
+            id: "subagents",
+            label: "Subagents",
+            getActivity: () => ({
+                providerId: "subagents",
+                label: "Subagents",
+                items: listMetasForParent(process.pid).map((meta) => {
+                    const status = effectiveStatus(meta);
+                    const active = status === "running" || status === "orphaned";
+                    return {
+                        id: meta.id,
+                        ...(meta.name ? { label: meta.name } : {}),
+                        status,
+                        active,
+                        unhealthy: status === "orphaned",
+                        terminal: !active,
+                        attention: status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited",
+                        startedAt: meta.startedAt,
+                        ...(meta.endedAt !== undefined ? { endedAt: meta.endedAt } : {}),
+                    };
+                }),
+            }),
+            onActivityChanged: onMetaChanged,
+        });
+    };
+    if (!goalReadySubscriptions.has(pi)) {
+        pi.events?.on?.(GOAL_READY_EVENT, emitProvider);
+        goalReadySubscriptions.add(pi);
+    }
+    emitProvider();
+}
+
 // ---- retired live status widget ------------------------------------------
 //
 // The shared background-work navigator owns the active subagent list. This
@@ -224,7 +265,7 @@ function hasSelfProcessIdentity(meta: RunMeta): boolean {
 
 function stopCurrentSessionSubagents(ctx: ExtensionContext): void {
     const origin = callbackOriginFromContext(ctx);
-    for (const summary of listMetas()) {
+    for (const summary of listMetasForParent(process.pid)) {
         if (!ownedByThisParent(summary)) continue;
         if (summary.status !== "running" && summary.status !== "orphaned") continue;
         if (!belongsToOrigin(summary, origin)) continue;
@@ -286,7 +327,7 @@ function enqueueCompletionCallback(pi: ExtensionAPI, id: string): void {
 
 /** Recover only records explicitly marked pending; legacy terminal runs never replay. */
 function recoverCompletionCallbacks(pi: ExtensionAPI): void {
-    for (const meta of listMetas()) {
+    for (const meta of listMetasForParent(process.pid)) {
         if (!ownedByThisParent(meta)) continue;
         enqueueCompletionCallback(pi, meta.id);
     }
@@ -504,15 +545,12 @@ function deliverHealthCallback(pi: ExtensionAPI | undefined, meta: RunMeta, stat
 function reconcileHealth(): void {
     const ctx = uiCtx;
     const pi = healthPi;
-    // Free work while the loop is already running: nothing else will ever
-    // reconcile a record whose parent is gone.
-    reconcileAbandonedRuns();
-    for (const summary of listMetas()) {
+    for (const summary of listMetasForParent(process.pid)) {
         if (!ownedByThisParent(summary)) continue;
         // running/orphaned: process reconcile. lost: durable callback recovery only.
         if (summary.status !== "running" && summary.status !== "orphaned" && summary.status !== "lost") continue;
         // Re-read under the id: finalizeRun / subagent_stop may have written a
-        // terminal status since listMetas() snapshotted.
+        // terminal status since the owned index was read.
         const meta = readMeta(summary.id);
         if (!meta) continue;
         if (meta.status !== "running" && meta.status !== "orphaned" && meta.status !== "lost") continue;
@@ -544,7 +582,7 @@ function reconcileHealth(): void {
         }
     }
     // Stop existing the moment nothing current-parent needs monitoring/recovery.
-    if (!needsMonitoring(listMetas())) stopHealthTicker();
+    if (!needsMonitoring(listMetasForParent(process.pid))) stopHealthTicker();
 }
 
 /**
@@ -691,17 +729,14 @@ function navigatorRunningCount(): number {
 }
 
 /**
- * The visible run set. `listMetas` reads and parses one `meta.json` per run in
- * the registry, so a caller that needs this twice should scan once and pass the
- * snapshot down (see `subagentWorkRows`) rather than ask again.
- *
- * Deliberately NOT cached across calls. A time-based memo here was tried and
- * reverted: it made a run created outside this process — another pi session's
- * spawn, or a test seeding one — invisible until the window expired, and the
- * navigator then acted on a set that no longer matched the registry.
+ * The visible run set. The durable origin index limits reads to this session;
+ * each rebuild still reads owned non-terminal metadata so external status
+ * changes are visible immediately without a time-based memo.
  */
 function sessionVisibleNavigatorRuns(now: number = Date.now()): RunMeta[] {
-    return navigatorVisibleRuns(listMetas())
+    const origin = activeCallbackOrigin;
+    if (!origin) return [];
+    return navigatorVisibleRuns(listMetasForOrigin(origin))
         .filter(belongsToActiveNavigatorSession)
         .filter((m) => !isExpiredTerminalNavigatorRun(m, now));
 }
@@ -1055,6 +1090,7 @@ export default function (pi: ExtensionAPI) {
     // coordinator follow-ups that fire outside a tool-call stack (#65).
     healthPi = pi;
     ensureSubagentProvider();
+    registerSubagentsGoalProvider(pi);
 
     type SpawnParams = {
         prompt: string; name?: string; model?: string; thinking?: ThinkingLevel; tools?: string;
@@ -1260,7 +1296,7 @@ export default function (pi: ExtensionAPI) {
             const cfg = loadConfig();
             const maxConcurrent = cfg.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
             const countRunning = () =>
-                listMetas().filter((m) => ownedByThisParent(m) && effectiveStatus(m) === "running").length;
+                listActiveMetasForParent(process.pid).filter((m) => effectiveStatus(m) === "running").length;
             // Shared with batch-spawn: reserve before any async work so an interleaved
             // batch cannot oversubscribe after this check and before writeMeta.
             const gate = getSharedCapacityGate(countRunning);
@@ -1351,7 +1387,7 @@ export default function (pi: ExtensionAPI) {
             const cfg = loadConfig();
             const maxConcurrent = cfg.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
             const countRunning = () =>
-                listMetas().filter((m) => ownedByThisParent(m) && effectiveStatus(m) === "running").length;
+                listActiveMetasForParent(process.pid).filter((m) => effectiveStatus(m) === "running").length;
             const launchAvailable = p.onCapacity === "launch-available";
             // Shared with single-spawn. Reservations count against maxConcurrent so a
             // concurrent single spawn cannot take a slot the batch already admitted.
@@ -1530,7 +1566,7 @@ export default function (pi: ExtensionAPI) {
         // Resume supervision reconciliation + durable health-callback recovery
         // across /reload while current-parent work still needs the ticker
         // (running/orphaned, or unmarked lost); it stops itself when idle.
-        if (needsMonitoring(listMetas())) ensureHealthTicker();
+        if (needsMonitoring(listMetasForParent(process.pid))) ensureHealthTicker();
     });
 
     pi.on("session_before_switch", () => {

package/node_modules/pi-better-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-subagents/registry.ts

@@ -7,7 +7,8 @@
  * for runs this process spawned.
  */
 
-import { mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { processExists } from "./spawn.ts";
@@ -151,7 +152,31 @@ function metaPathFor(id: string): string {
 }
 
 let seq = 0;
+const metaCache = new Map<string, RunMeta>();
+// Owned snapshots are process-resident. A cheap directory signature catches
+// cross-process index changes before any cached IDs are reused.
+const indexIdsCache = new Map<string, { ids: Set<string>; signature: string }>();
+const initializedIndexes = new Set<string>();
 const metaChangedListeners = new Set<() => void>();
+const registryIo = { fullDirectoryReads: 0, indexDirectoryReads: 0, metadataFileReads: 0, indexRevisionChecks: 0 };
+
+export interface RegistryIoMetrics {
+    fullDirectoryReads: number;
+    indexDirectoryReads: number;
+    metadataFileReads: number;
+    indexRevisionChecks: number;
+}
+
+export function getRegistryIoMetrics(): RegistryIoMetrics {
+    return { ...registryIo };
+}
+
+export function resetRegistryIoMetrics(): void {
+    registryIo.fullDirectoryReads = 0;
+    registryIo.indexDirectoryReads = 0;
+    registryIo.metadataFileReads = 0;
+    registryIo.indexRevisionChecks = 0;
+}
 /** Monotonic, readable, collision-free run id: `sa_<base36-time>_<seq>`. */
 export function nextRunId(): string {
     seq += 1;
@@ -161,6 +186,8 @@ export function nextRunId(): string {
 export function writeMeta(meta: RunMeta): void {
     mkdirSync(runDir(meta.id), { recursive: true });
     writeFileSync(metaPathFor(meta.id), JSON.stringify(meta, null, 2));
+    metaCache.set(meta.id, meta);
+    indexMeta(meta);
     for (const listener of metaChangedListeners) {
         try { listener(); } catch { /* best effort */ }
     }
@@ -173,26 +200,203 @@ export function onMetaChanged(listener: () => void): () => void {
 
 export function readMeta(id: string): RunMeta | undefined {
     try {
-        return JSON.parse(readFileSync(metaPathFor(id), "utf-8")) as RunMeta;
+        registryIo.metadataFileReads += 1;
+        const meta = JSON.parse(readFileSync(metaPathFor(id), "utf-8")) as RunMeta;
+        metaCache.set(id, meta);
+        return meta;
     } catch {
+        metaCache.delete(id);
         return undefined;
     }
 }
 
+export function removeMetaArtifacts(meta: RunMeta): boolean {
+    try {
+        rmSync(runDir(meta.id), { recursive: true, force: true });
+        metaCache.delete(meta.id);
+        removeIndexEntry(join(baseDir(), "by-parent", String(meta.spawnPid)), meta.id);
+        removeIndexEntry(join(baseDir(), "by-parent-active", String(meta.spawnPid)), meta.id);
+        removeIndexEntry(join(baseDir(), "by-origin", originKey(originOf(meta))), meta.id);
+        for (const listener of metaChangedListeners) {
+            try { listener(); } catch { /* best effort */ }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 /** All runs, newest first. */
 export function listMetas(): RunMeta[] {
     let ids: string[];
     try {
+        registryIo.fullDirectoryReads += 1;
         ids = readdirSync(join(baseDir(), "runs"));
     } catch {
         return [];
     }
     return ids
-        .map(readMeta)
+        .map(readMetaForSweep)
         .filter((m): m is RunMeta => m !== undefined)
         .sort((a, b) => b.startedAt - a.startedAt);
 }
 
+export function listMetasForParent(parentPid: number): RunMeta[] {
+    const directory = join(baseDir(), "by-parent", String(parentPid));
+    ensureIndex(directory, (meta) => meta.spawnPid === parentPid);
+    return readIndexedMetas(directory).filter((meta) => meta.spawnPid === parentPid);
+}
+
+export function listActiveMetasForParent(parentPid: number): RunMeta[] {
+    const directory = join(baseDir(), "by-parent-active", String(parentPid));
+    ensureActiveParentIndex(directory, parentPid);
+    return readIndexedMetas(directory)
+        .filter((meta) => meta.spawnPid === parentPid && isActiveStatus(meta.status));
+}
+
+export function listMetasForOrigin(origin: RunCallbackOrigin): RunMeta[] {
+    const directory = join(baseDir(), "by-origin", originKey(origin));
+    ensureIndex(directory, (meta) => belongsToOrigin(meta, origin));
+    return readIndexedMetas(directory).filter((meta) => belongsToOrigin(meta, origin));
+}
+
+function readMetaForSweep(id: string): RunMeta | undefined {
+    const cached = metaCache.get(id);
+    if (cached && cached.status !== "running" && cached.status !== "orphaned") return cached;
+    return readMeta(id);
+}
+
+function readIndexedMetas(directory: string): RunMeta[] {
+    return readIndexIds(directory)
+        .map((id) => metaCache.get(id) ?? readMeta(id))
+        .filter((meta): meta is RunMeta => meta !== undefined)
+        .sort((a, b) => b.startedAt - a.startedAt);
+}
+
+function indexMeta(meta: RunMeta): void {
+    try {
+        writeIndexEntry(join(baseDir(), "by-parent", String(meta.spawnPid)), meta.id);
+        const activeDirectory = join(baseDir(), "by-parent-active", String(meta.spawnPid));
+        if (isActiveStatus(meta.status)) writeIndexEntry(activeDirectory, meta.id);
+        else removeIndexEntry(activeDirectory, meta.id);
+        writeIndexEntry(join(baseDir(), "by-origin", originKey(originOf(meta))), meta.id);
+    } catch {
+        // Indexes are accelerators; meta.json remains authoritative.
+    }
+}
+
+function writeIndexEntry(directory: string, id: string): void {
+    mkdirSync(directory, { recursive: true });
+    const cached = indexIdsCache.get(directory);
+    const cacheWasCurrent = cached ? cached.signature === indexDirectorySignature(directory) : false;
+    try {
+        writeFileSync(join(directory, id), "", { flag: "wx" });
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    if (cached && cacheWasCurrent) {
+        cached.ids.add(id);
+        cached.signature = indexDirectorySignature(directory);
+    } else if (cached) {
+        indexIdsCache.delete(directory);
+    }
+}
+
+function removeIndexEntry(directory: string, id: string): void {
+    const cached = indexIdsCache.get(directory);
+    const cacheWasCurrent = cached ? cached.signature === indexDirectorySignature(directory) : false;
+    try { unlinkSync(join(directory, id)); } catch { /* stale index entries are harmless */ }
+    if (cached && cacheWasCurrent) {
+        cached.ids.delete(id);
+        cached.signature = indexDirectorySignature(directory);
+    } else if (cached) {
+        indexIdsCache.delete(directory);
+    }
+}
+
+function readIndexIds(directory: string): string[] {
+    const signature = indexDirectorySignature(directory);
+    const cached = indexIdsCache.get(directory);
+    if (cached && cached.signature === signature) return [...cached.ids];
+    try {
+        registryIo.indexDirectoryReads += 1;
+        const ids = new Set(readdirSync(directory).filter((id) => id !== ".initialized"));
+        indexIdsCache.set(directory, { ids, signature: indexDirectorySignature(directory) });
+        return [...ids];
+    } catch {
+        indexIdsCache.delete(directory);
+        return [];
+    }
+}
+
+function isActiveStatus(status: RunStatus): boolean {
+    return status === "running" || status === "orphaned";
+}
+
+function indexDirectorySignature(directory: string): string {
+    registryIo.indexRevisionChecks += 1;
+    try {
+        const stat = statSync(directory);
+        return `${stat.dev}:${stat.ino}:${stat.mtimeMs}:${stat.ctimeMs}`;
+    } catch {
+        return "missing";
+    }
+}
+
+function ensureIndex(directory: string, matches: (meta: RunMeta) => boolean): void {
+    if (initializedIndexes.has(directory)) return;
+    try {
+        readFileSync(join(directory, ".initialized"));
+        initializedIndexes.add(directory);
+        return;
+    } catch {
+        // Existing registries are backfilled once for each owner.
+    }
+    indexIdsCache.delete(directory);
+    const owned = listMetas().filter(matches);
+    mkdirSync(directory, { recursive: true });
+    for (const meta of owned) writeIndexEntry(directory, meta.id);
+    writeFileSync(join(directory, ".initialized"), "1");
+    initializedIndexes.add(directory);
+}
+
+function ensureActiveParentIndex(directory: string, parentPid: number): void {
+    if (initializedIndexes.has(directory)) return;
+    try {
+        readFileSync(join(directory, ".initialized"));
+        initializedIndexes.add(directory);
+        return;
+    } catch {
+        // Build the active set from the already owner-scoped parent index.
+    }
+    indexIdsCache.delete(directory);
+    const active = listMetasForParent(parentPid).filter((meta) => isActiveStatus(meta.status));
+    mkdirSync(directory, { recursive: true });
+    for (const meta of active) writeIndexEntry(directory, meta.id);
+    writeFileSync(join(directory, ".initialized"), "1");
+    initializedIndexes.add(directory);
+}
+
+function originOf(meta: RunMeta): RunCallbackOrigin {
+    return meta.callbackOrigin ?? { cwd: meta.cwd };
+}
+
+function belongsToOrigin(meta: RunMeta, origin: RunCallbackOrigin): boolean {
+    const candidate = originOf(meta);
+    if (candidate.cwd !== origin.cwd) return false;
+    if (candidate.sessionId || origin.sessionId) return candidate.sessionId === origin.sessionId;
+    return true;
+}
+
+function originKey(origin: RunCallbackOrigin): string {
+    return createHash("sha256")
+        .update(origin.cwd)
+        .update("\0")
+        .update(origin.sessionId ?? "")
+        .digest("hex")
+        .slice(0, 24);
+}
+
 /**
  * Reconcile the recorded status with reality for display. A run marked
  * "running" whose PID is no longer alive exited without our handler firing