@fitchmultz/pi-subagents 0.52.18 → 0.52.20

package/src/pi-intercom/broker/snapshots.ts

@@ -202,17 +202,52 @@ class SnapshotRecords<T extends { readonly topic: string }> {
   }
 }
 
-interface PreparedTopicChange {
-  readonly topic?: TopicUpdate;
-  readonly subscription?: TopicSubscription;
-  readonly unsubscribe?: string;
-  readonly publication?: TopicUpdate;
-  readonly restore: boolean;
-  readonly changed: boolean;
-  readonly bytes: number;
+type PreparedTopicChange =
+  | { readonly kind: "unchanged"; readonly restore: false }
+  | { readonly kind: "normalize"; readonly restore: true }
+  | {
+      readonly kind: "publish";
+      readonly restore: false;
+      readonly topic: TopicUpdate;
+      readonly bytes: number;
+    }
+  | {
+      readonly kind: "restore-topic";
+      readonly restore: true;
+      readonly topic: TopicUpdate;
+      readonly bytes: number;
+    }
+  | {
+      readonly kind: "subscription";
+      readonly restore: boolean;
+      readonly subscription: TopicSubscription;
+      readonly bytes: number;
+    }
+  | { readonly kind: "unsubscribe"; readonly restore: false; readonly topic: string };
+
+const UNCHANGED: PreparedTopicChange = { kind: "unchanged", restore: false };
+
+function updatedTopic(prepared: PreparedTopicChange) {
+  return prepared.kind === "publish" || prepared.kind === "restore-topic" ? prepared : undefined;
+}
+
+function subscriptionKey(prepared: PreparedTopicChange): string | undefined {
+  switch (prepared.kind) {
+    case "subscription":
+      return prepared.subscription.topic;
+    case "unsubscribe":
+      return prepared.topic;
+    case "unchanged":
+    case "normalize":
+    case "publish":
+    case "restore-topic":
+      return undefined;
+  }
 }
 
-const UNCHANGED: PreparedTopicChange = { restore: false, changed: false, bytes: 0 };
+export function preparedPublication(prepared: PreparedTopicChange): TopicUpdate | undefined {
+  return prepared.kind === "publish" ? prepared.topic : undefined;
+}
 
 /** Keep committed records indexed; restores validate only new bytes and cached envelope maxima. */
 export class TopicSnapshot {
@@ -236,62 +271,64 @@ export class TopicSnapshot {
       throw new Error("Topic snapshots unavailable for this client");
     }
     const mutation = topicMutation(change);
-    const base = { restore: change.action === "restore", changed: true, bytes: 0 };
     switch (mutation.kind) {
       case "publication":
-        return this.preparePublication(mutation, base);
+        return this.preparePublication(mutation);
       case "subscription":
         return {
-          ...base,
+          kind: "subscription",
+          restore: change.action === "restore",
           subscription: mutation.subscription,
           bytes: intercomMessageSizeBytes(mutation.subscription),
         };
       case "unsubscribe":
-        return { ...base, unsubscribe: mutation.topic };
+        return { kind: "unsubscribe", restore: false, topic: mutation.topic };
     }
   }
 
   private preparePublication(
     mutation: Extract<TopicMutation, { readonly kind: "publication" }>,
-    base: PreparedTopicChange,
   ): PreparedTopicChange {
     const previous = this.topics.get(mutation.topic.topic);
     const update = publicationUpdate(mutation.topic, previous, mutation.publish);
     if (!mutation.publish && (previous?.revision ?? 0) >= update.revision) {
-      return base;
+      return { kind: "normalize", restore: true };
     }
     return {
-      ...base,
+      ...(mutation.publish
+        ? ({ kind: "publish", restore: false } as const)
+        : ({ kind: "restore-topic", restore: true } as const)),
       topic: update,
       bytes: intercomMessageSizeBytes(update),
-      ...(mutation.publish ? { publication: update } : {}),
     };
   }
 
   snapshot(info: SessionInfo, prepared = UNCHANGED): SessionInfo {
-    const topics = this.topics.valuesAfter(prepared.topic?.topic, prepared.topic, prepared.changed);
+    const topic = updatedTopic(prepared)?.topic;
+    const subscription = prepared.kind === "subscription" ? prepared.subscription : undefined;
+    const changed = prepared.kind !== "unchanged";
+    const topics = this.topics.valuesAfter(topic?.topic, topic, changed);
     const subscriptions = this.subscriptions.valuesAfter(
-      prepared.subscription?.topic ?? prepared.unsubscribe,
-      prepared.subscription,
-      prepared.changed,
+      subscriptionKey(prepared),
+      subscription,
+      changed,
     );
     return {
       ...info,
       ...(topics !== undefined ? { topics } : {}),
       ...(subscriptions !== undefined ? { subscriptions } : {}),
-      ...(prepared.publication ? { lastIntercomActivity: Date.now() } : {}),
+      ...(preparedPublication(prepared) ? { lastIntercomActivity: Date.now() } : {}),
     };
   }
 
   validateRestore(info: SessionInfo, prepared: PreparedTopicChange, requestId: string): void {
     snapshotFrames(requestId, [{ ...info, topics: [], subscriptions: [] }], true);
-    const topicBytes = this.topics.maximumAfter(
-      prepared.topic?.topic,
-      prepared.topic ? prepared.bytes : 0,
-    );
+    const topic = updatedTopic(prepared);
+    const subscription = prepared.kind === "subscription" ? prepared : undefined;
+    const topicBytes = this.topics.maximumAfter(topic?.topic.topic, topic?.bytes ?? 0);
     const subscriptionBytes = this.subscriptions.maximumAfter(
-      prepared.subscription?.topic,
-      prepared.subscription ? prepared.bytes : 0,
+      subscription?.subscription.topic,
+      subscription?.bytes ?? 0,
     );
     for (const [field, bytes] of [
       ["topics", topicBytes],
@@ -311,16 +348,24 @@ export class TopicSnapshot {
   }
 
   commit(prepared: PreparedTopicChange): void {
-    if (prepared.changed) {
-      this.topics.accept();
-      this.subscriptions.accept();
+    if (prepared.kind === "unchanged") {
+      return;
     }
-    if (prepared.topic) {
-      this.topics.set(prepared.topic, prepared.bytes);
-    } else if (prepared.subscription) {
-      this.subscriptions.set(prepared.subscription, prepared.bytes);
-    } else if (prepared.unsubscribe !== undefined) {
-      this.subscriptions.delete(prepared.unsubscribe);
+    this.topics.accept();
+    this.subscriptions.accept();
+    switch (prepared.kind) {
+      case "publish":
+      case "restore-topic":
+        this.topics.set(prepared.topic, prepared.bytes);
+        return;
+      case "subscription":
+        this.subscriptions.set(prepared.subscription, prepared.bytes);
+        return;
+      case "unsubscribe":
+        this.subscriptions.delete(prepared.topic);
+        return;
+      case "normalize":
+        return;
     }
   }
 }

package/src/pi-intercom/broker/spawn-claim.ts

@@ -0,0 +1,98 @@
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { hasErrorCode } from "../../shared/unknown.ts";
+import { brokerPidRecord, isLinuxProcessReplaced } from "./pid.ts";
+
+type OwnerState = "live" | "exited" | "uncertain";
+
+function ownerState(fd: number): OwnerState {
+  try {
+    const lines = readFileSync(fd, "utf8").split("\n");
+    const first = lines[0] ?? "";
+    const pid = Number(first);
+    if (!/^[1-9]\d*$/.test(first) || !Number.isSafeInteger(pid)) {
+      return "uncertain";
+    }
+    process.kill(pid, 0);
+    return isLinuxProcessReplaced(pid, lines.slice(2).join("\n")) ? "exited" : "live";
+  } catch (error) {
+    return hasErrorCode(error, "ESRCH") ? "exited" : "uncertain";
+  }
+}
+
+/** The open descriptor pins the original inode until its own cleanup finishes. */
+function removeOwned(file: string, fd: number): boolean {
+  try {
+    const owned = fstatSync(fd, { bigint: true });
+    const current = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+    if (current?.dev !== owned.dev || current.ino !== owned.ino) {
+      return false;
+    }
+    unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function reclaimExited(file: string): boolean {
+  let fd: number;
+  try {
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error) {
+    return hasErrorCode(error, "ENOENT");
+  }
+  try {
+    return ownerState(fd) === "exited" && removeOwned(file, fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function publishClaim(file: string, fd: number): () => void {
+  const release = () => {
+    try {
+      removeOwned(file, fd);
+    } finally {
+      closeSync(fd);
+    }
+  };
+  try {
+    // Keep legacy PID/timestamp lines; qualified native identity can prove later PID reuse.
+    const record = brokerPidRecord();
+    const identity = record.slice(record.indexOf("\n") + 1);
+    writeFileSync(fd, `${process.pid}\n${Date.now()}\n${identity}`);
+    return release;
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+
+/** An acquired claim returns its release operation; live or uncertain claims remain untouched. */
+export function acquireSpawnClaim(file: string): (() => void) | undefined {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    let fd: number;
+    try {
+      fd = openSync(file, "wx", 0o600);
+    } catch (error) {
+      if (!hasErrorCode(error, "EEXIST")) {
+        throw error;
+      }
+      if (reclaimExited(file)) {
+        continue;
+      }
+      return;
+    }
+    return publishClaim(file, fd);
+  }
+  return;
+}

package/src/pi-intercom/broker/spawn.ts

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import net from "net";
@@ -12,6 +12,7 @@ import {
   prepareBrokerSocketPath,
 } from "./paths.ts";
 import { isBrokerPidReused } from "./pid.ts";
+import { acquireSpawnClaim } from "./spawn-claim.ts";
 import { errorMessage, hasErrorCode } from "../../shared/unknown.ts";
 
 const EXTENSION_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
@@ -85,8 +86,8 @@ export async function spawnBrokerIfNeeded(
     return;
   }
 
-  const ownsLock = acquireSpawnLock();
-  if (!ownsLock) {
+  const release = acquireSpawnClaim(BROKER_SPAWN_LOCK);
+  if (release === undefined) {
     await waitForBroker();
     return;
   }
@@ -138,7 +139,7 @@ export async function spawnBrokerIfNeeded(
         });
     });
   } finally {
-    releaseSpawnLock();
+    release();
   }
 }
 
@@ -153,26 +154,33 @@ export async function assertBrokerCanStart(): Promise<void> {
   await stopUnhealthyBrokerBeforeSpawn();
 }
 
-function readLivePid(pidPath: string): number | null {
-  if (!existsSync(pidPath)) {
-    return null;
-  }
+type BrokerOwner =
+  | { readonly kind: "absent" }
+  | { readonly kind: "live"; readonly pid: number }
+  | { readonly kind: "uncertain"; readonly reason: string };
+
+function readBrokerOwner(pidPath: string): BrokerOwner {
   let raw: string;
   try {
     raw = readFileSync(pidPath, "utf-8");
-  } catch {
-    return null;
+  } catch (error) {
+    return hasErrorCode(error, "ENOENT")
+      ? { kind: "absent" }
+      : { kind: "uncertain", reason: `Cannot read broker PID record: ${errorMessage(error)}` };
   }
-  const pid = parseInt(raw.trim(), 10);
-  if (!Number.isFinite(pid) || pid <= 0) {
-    return null;
+  const first = raw.trim().split("\n")[0] ?? "";
+  const pid = Number(first);
+  if (!/^[1-9]\d*$/.test(first) || !Number.isSafeInteger(pid)) {
+    return { kind: "uncertain", reason: "Broker PID record is invalid" };
   }
   try {
     process.kill(pid, 0);
   } catch (error) {
-    return hasErrorCode(error, "EPERM") ? pid : null;
+    return hasErrorCode(error, "ESRCH")
+      ? { kind: "absent" }
+      : { kind: "uncertain", reason: `Cannot establish broker PID ${pid}: ${errorMessage(error)}` };
   }
-  return isBrokerPidReused(pid, raw) ? null : pid;
+  return isBrokerPidReused(pid, raw) ? { kind: "absent" } : { kind: "live", pid };
 }
 
 async function previousBrokerWarning(): Promise<string | undefined> {
@@ -183,9 +191,10 @@ async function previousBrokerWarning(): Promise<string | undefined> {
       return "An older agent-directory Intercom broker is still running. Its peers are not part of shared same-user discovery until they reload with the updated extension. Existing sessions and accepted work are untouched; no legacy fallback is used.";
     }
   }
-  const previousPid = readLivePid(join(getPiAgentDir(), "intercom", "broker.pid"));
-  if (previousPid !== null) {
-    return `Older Intercom broker PID ${previousPid} may still own accepted work. Its peers need to reload with the updated extension to join shared same-user discovery. Nothing was stopped or replaced; no legacy fallback is used.`;
+  const previous = readBrokerOwner(join(getPiAgentDir(), "intercom", "broker.pid"));
+  if (previous.kind !== "absent") {
+    const owner = previous.kind === "live" ? `PID ${previous.pid}` : "with uncertain PID identity";
+    return `Older Intercom broker ${owner} may still own accepted work. Its peers need to reload with the updated extension to join shared same-user discovery. Nothing was stopped or replaced; no legacy fallback is used.`;
   }
   return undefined;
 }
@@ -194,13 +203,19 @@ export async function stopUnhealthyBrokerBeforeSpawn(): Promise<void> {
   if (await checkSocketConnectable()) {
     return;
   }
-  const pid = readLivePid(BROKER_PID);
-  if (pid === null) {
-    return;
+  const owner = readBrokerOwner(BROKER_PID);
+  switch (owner.kind) {
+    case "absent":
+      return;
+    case "live":
+      throw new Error(
+        `Intercom broker PID ${owner.pid} may still own accepted work but its socket is unhealthy; refusing to spawn a second broker. Let the broker exit normally, then retry.`,
+      );
+    case "uncertain":
+      throw new Error(
+        `${owner.reason}; refusing to spawn a second broker while ownership is uncertain.`,
+      );
   }
-  throw new Error(
-    `Intercom broker PID ${pid} may still own accepted work but its socket is unhealthy; refusing to spawn a second broker. Let the broker exit normally, then retry.`,
-  );
 }
 
 async function checkSocketConnectable(): Promise<boolean> {
@@ -227,63 +242,6 @@ function checkOneSocket(brokerSocket: string): Promise<boolean> {
   });
 }
 
-function acquireSpawnLock(): boolean {
-  const maxRetries = 5;
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      writeFileSync(BROKER_SPAWN_LOCK, `${process.pid}\n${Date.now()}\n`, { flag: "wx" });
-      return true;
-    } catch (error) {
-      if (!hasErrorCode(error, "EEXIST")) {
-        throw error;
-      }
-      if (isSpawnLockStale()) {
-        releaseSpawnLock();
-        continue;
-      }
-      return false;
-    }
-  }
-  return false;
-}
-
-function isSpawnLockStale(): boolean {
-  if (!existsSync(BROKER_SPAWN_LOCK)) {
-    return false;
-  }
-
-  try {
-    const [pidLine = "", createdAtLine = "0"] = readFileSync(BROKER_SPAWN_LOCK, "utf-8")
-      .trim()
-      .split("\n");
-    const pid = Number.parseInt(pidLine, 10);
-    const createdAt = Number.parseInt(createdAtLine, 10);
-    const ageMs = Date.now() - createdAt;
-
-    if (Number.isFinite(pid)) {
-      try {
-        process.kill(pid, 0);
-      } catch {
-        // The process that created the lock is gone.
-        return true;
-      }
-    }
-
-    return !Number.isFinite(createdAt) || ageMs > 10_000;
-  } catch {
-    // Unreadable lock contents are treated as stale so a new broker can start.
-    return true;
-  }
-}
-
-function releaseSpawnLock(): void {
-  try {
-    unlinkSync(BROKER_SPAWN_LOCK);
-  } catch {
-    // Another cleanup path may already have removed the lock.
-  }
-}
-
 async function waitForBroker(timeoutMs = 5000): Promise<void> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
@@ -294,5 +252,7 @@ async function waitForBroker(timeoutMs = 5000): Promise<void> {
     // Polling waits between probes rather than starting an unbounded batch.
     await sleep(100);
   }
-  throw new Error("Broker failed to start within timeout");
+  throw new Error(
+    `Broker failed to start within timeout. Startup claim: ${BROKER_SPAWN_LOCK}. Live or uncertain owners are not reclaimed.`,
+  );
 }

package/src/pi-intercom/lifecycle.ts

@@ -24,14 +24,21 @@ type ContextSnapshot = Readonly<Record<keyof ContextTarget, string | null>> &
     readonly guardedDelivery: 1 | null;
   };
 
+type ContextState =
+  | { readonly kind: "inactive"; readonly epoch: number }
+  | { readonly kind: "invalidated"; readonly epoch: number; readonly sessionId: string }
+  | {
+      readonly kind: "live";
+      readonly epoch: number;
+      readonly context: ExtensionContext;
+      readonly sessionId: string;
+      readonly incarnation: string;
+    };
+
 /** Owns native context validity and occupancy, never journal or socket state. */
 export class IntercomLifecycle {
-  private context: ExtensionContext | null = null;
-  private sessionId: string | null = null;
+  private state: ContextState = { kind: "inactive", epoch: 0 };
   private model = "unknown";
-  private disposed = true;
-  private epoch = 0;
-  private incarnation: string | null = null;
   private peerId: string | null = null;
   private guardedDelivery = false;
   private applicationGuard: string | undefined;
@@ -47,10 +54,10 @@ export class IntercomLifecycle {
     this.lineage = lineage;
   }
   get generation(): number {
-    return this.epoch;
+    return this.state.epoch;
   }
   get currentSessionId(): string | null {
-    return this.sessionId;
+    return this.state.kind === "inactive" ? null : this.state.sessionId;
   }
   get toolCount(): number {
     return this.tools.size;
@@ -88,7 +95,7 @@ export class IntercomLifecycle {
     request.respond(this.snapshot());
   }
   snapshot(): ContextSnapshot {
-    if (!this.live()) {
+    if (this.state.kind !== "live" || !this.live()) {
       return {
         version: 1,
         rootSessionId: null,
@@ -100,10 +107,10 @@ export class IntercomLifecycle {
     }
     return {
       version: 1,
-      rootSessionId: this.lineage?.rootSessionId ?? this.sessionId,
+      rootSessionId: this.lineage?.rootSessionId ?? this.state.sessionId,
       parentSessionId: this.lineage?.parentSessionId,
       peerId: this.peerId,
-      incarnation: this.incarnation,
+      incarnation: this.state.incarnation,
       connected: this.peerId !== null,
       guardedDelivery: this.guardedDelivery ? 1 : null,
       applicationGuard: this.applicationGuard,
@@ -135,39 +142,43 @@ export class IntercomLifecycle {
     );
   }
   start(ctx: ExtensionContext): number {
-    this.disposed = false;
-    this.epoch += 1;
-    this.context = ctx;
-    this.sessionId = ctx.sessionManager.getSessionId();
-    this.incarnation = randomUUID();
+    this.state = {
+      kind: "live",
+      epoch: this.state.epoch + 1,
+      context: ctx,
+      sessionId: ctx.sessionManager.getSessionId(),
+      incarnation: randomUUID(),
+    };
     this.applicationGuard = undefined;
     this.model = ctx.model?.id ?? "unknown";
     this.running = false;
     this.activity = 0;
     this.tools.clear();
     this.transport(null);
-    return this.epoch;
+    return this.state.epoch;
   }
   invalidate(): void {
-    this.disposed = true;
-    this.epoch += 1;
+    const epoch = this.state.epoch + 1;
+    this.state =
+      this.state.kind === "inactive"
+        ? { kind: "inactive", epoch }
+        : { kind: "invalidated", epoch, sessionId: this.state.sessionId };
     this.running = false;
     this.tools.clear();
     this.publishContext();
   }
   clear(): void {
-    this.context = null;
-    this.sessionId = null;
+    this.state = { kind: "inactive", epoch: this.state.epoch };
   }
   live(
-    ctx: ExtensionContext | null = this.context,
-    generation = this.epoch,
+    ctx: ExtensionContext | null = this.state.kind === "live" ? this.state.context : null,
+    generation = this.state.epoch,
   ): ExtensionContext | null {
-    if (this.disposed || generation !== this.epoch || !ctx) {
+    if (this.state.kind !== "live" || generation !== this.state.epoch || !ctx) {
       return null;
     }
     try {
-      if (this.sessionId !== null && ctx.sessionManager.getSessionId() !== this.sessionId) {
+      if (ctx.sessionManager.getSessionId() !== this.state.sessionId) {
         return null;
       }
       // Reading a native property detects invalidated contexts without modifying them.
@@ -240,12 +251,12 @@ export class IntercomLifecycle {
   }
   async registration(pendingAsks: number): Promise<Omit<SessionInfo, "id">> {
     const live = this.live();
-    if (!live || this.sessionId === null) {
+    if (!live || this.state.kind !== "live") {
       throw new Error("Intercom runtime not initialized");
     }
     return {
-      ...this.identity(this.sessionId),
-      incarnation: this.incarnation ?? undefined,
+      ...this.identity(this.state.sessionId),
+      incarnation: this.state.incarnation,
       guardedDelivery: 1,
       applicationGuard: this.applicationGuard,
       cwd: live.cwd,