@fitchmultz/pi-subagents 0.52.18 → 0.52.19

package/src/agent/view.ts

@@ -15,7 +15,7 @@ import {
 import type { RunsInput } from "./tool-schemas.ts";
 import { conversation, read, runDirectory } from "./storage.ts";
 import { published } from "./notifications.ts";
-import { readCanonicalResult, readResult } from "./usage.ts";
+import { accountingFields, accountingState, readCanonicalResult, readResult } from "./usage.ts";
 import { Type } from "./typebox.ts";
 
 const commandMetadataSchema = Type.Pick(commandSchema, ["id", "runId", "action", "createdAt"]);
@@ -72,18 +72,20 @@ function toolResult(value: unknown, text: string): ToolReply {
   return { content: [{ type: "text" as const, text }], details: value };
 }
 function receiptResult(result: Result | undefined) {
-  return result === undefined
-    ? undefined
-    : {
-        id: result.id,
-        owner: result.owner,
-        status: result.status,
-        endedAt: result.endedAt,
-        terminalEntryId: result.terminalEntryId,
-        error: result.error,
-        accountingError: result.accountingError,
-        accountingPending: result.accountingPending,
-      };
+  if (result === undefined) {
+    return;
+  }
+  const { contributions: _contributions, ...accounting } = accountingFields(
+    accountingState(result),
+  );
+  return {
+    id: result.id,
+    owner: result.owner,
+    status: result.status,
+    endedAt: result.endedAt,
+    error: result.error,
+    ...accounting,
+  };
 }
 /** `observed` holds batched liveness by actor token; any other actor gets a fresh check. */
 function processView(base: string, launch: Launch, observed?: ReadonlyMap<string, boolean>) {

package/src/agent/wake.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import assert from "node:assert/strict";
 import { journalStamp } from "../shared/native-journal.ts";
 import { missing } from "./storage.ts";
 
@@ -21,10 +22,12 @@ export type WatchState = "unwatched" | "armed" | "changed" | "watching";
 
 /** Native change hints for one directory identity; owners still reconcile canonical files. */
 export class DirectoryWatch {
-  private watcher?: fs.FSWatcher | undefined;
-  private armed = "";
+  private state:
+    | { readonly kind: "unarmed" | "polling" }
+    | { readonly kind: "armed"; readonly watcher: fs.FSWatcher; readonly identity: string } = {
+    kind: "unarmed",
+  };
   private checked = "";
-  private failed = false;
   private readonly directory: string;
   private readonly relevant: (file: string | null) => boolean;
   private readonly wake: () => void;
@@ -38,40 +41,40 @@ export class DirectoryWatch {
     const identity = stat?.isDirectory() === true ? `${stat.dev}:${stat.ino}` : "";
     const checked = this.checked;
     this.checked = stat === undefined ? "" : `${identity}:${stat.mtimeNs}:${stat.ctimeNs}`;
-    if (this.watcher !== undefined && identity === this.armed) {
+    if (this.state.kind === "armed" && identity === this.state.identity) {
       return checked === this.checked ? "watching" : "changed";
     }
     // A replaced directory leaves an inode watch silent on Linux.
     this.close();
-    return identity === "" || this.failed ? "unwatched" : this.arm(identity);
+    return identity === "" || this.state.kind === "polling" ? "unwatched" : this.arm(identity);
   }
   private arm(identity: string): WatchState {
     try {
       const watcher = fs.watch(this.directory, { persistent: false }, (_event, file) => {
-        if (watcher === this.watcher && this.relevant(file)) {
+        if (this.state.kind === "armed" && watcher === this.state.watcher && this.relevant(file)) {
           this.wake();
         }
       });
       watcher.on("error", () => {
-        if (watcher === this.watcher) {
-          this.failed = true;
-          this.close();
+        if (this.state.kind === "armed" && watcher === this.state.watcher) {
+          watcher.close();
+          this.state = { kind: "polling" };
           this.wake();
         }
       });
-      this.watcher = watcher;
-      this.armed = identity;
+      this.state = { kind: "armed", watcher, identity };
       return "armed";
     } catch (error) {
       // Unsupported platforms and watch limits keep their owner's polling fallback.
-      this.failed = !missing(error);
+      this.state = { kind: missing(error) ? "unarmed" : "polling" };
       return "unwatched";
     }
   }
   close(): void {
-    this.watcher?.close();
-    this.watcher = undefined;
-    this.armed = "";
+    if (this.state.kind === "armed") {
+      this.state.watcher.close();
+      this.state = { kind: "unarmed" };
+    }
   }
 }
 
@@ -90,6 +93,7 @@ export class Wake {
   }
   /** Returns at once for a wake raised since the last take. */
   async sleep(ms: number): Promise<void> {
+    assert.equal(this.resolve, undefined, "A Wake belongs to one waiting owner loop.");
     if (this.raised) {
       return;
     }

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

@@ -29,6 +29,7 @@ import {
   snapshotFrames,
   TopicSnapshot,
   publicationMessage,
+  preparedPublication,
   deliveryAcknowledgement,
   shouldReplaceDelivery,
 } from "./snapshots.ts";
@@ -245,7 +246,7 @@ class IntercomBroker {
         ? session.info
         : session.topics.snapshot(session.info, prepared);
       const from = messageSender(nextInfo);
-      const deliveries = this.planPublications(currentId, from, prepared.publication);
+      const deliveries = this.planPublications(currentId, from, preparedPublication(prepared));
       // Validate every frame before committing state or delivering publications.
       if (prepared.restore) {
         session.topics.validateRestore(session.info, prepared, requestId);

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.`,
+  );
 }