@fitchmultz/pi-subagents 0.52.17 → 0.52.19

package/src/agent/usage.ts

@@ -8,12 +8,49 @@ import { Assert } from "./typebox.ts";
 import {
   contributionsSchema,
   resultSchema,
+  type AccountingState,
   type Contribution,
   type Launch,
   type Result,
 } from "./contracts.ts";
 import { read, runDirectory, write } from "./storage.ts";
 
+/** Pending repair remains authoritative until its native terminal is published and validated. */
+export function accountingState(result: Result | undefined): AccountingState {
+  if (result?.accountingPending !== undefined) {
+    return { kind: "pending", pending: result.accountingPending, error: result.accountingError };
+  }
+  const terminalEntryId = result?.terminalEntryId;
+  if (result?.contributions !== undefined) {
+    return { kind: "verified", contributions: result.contributions, terminalEntryId };
+  }
+  return result?.accountingError === undefined
+    ? { kind: "unrecorded", terminalEntryId }
+    : { kind: "unavailable", error: result.accountingError, terminalEntryId };
+}
+
+export function accountingFields(
+  state: AccountingState,
+): Pick<Result, "contributions" | "accountingPending" | "accountingError" | "terminalEntryId"> {
+  const terminal =
+    state.kind !== "pending" && state.terminalEntryId !== undefined
+      ? { terminalEntryId: state.terminalEntryId }
+      : {};
+  switch (state.kind) {
+    case "unrecorded":
+      return terminal;
+    case "verified":
+      return { contributions: state.contributions, ...terminal };
+    case "pending":
+      return {
+        accountingPending: state.pending,
+        ...(state.error === undefined ? {} : { accountingError: state.error }),
+      };
+    case "unavailable":
+      return { accountingError: state.error, ...terminal };
+  }
+}
+
 /** Billing evidence of one native entry. Missing required usage is an error only outside a baseline. */
 function billing(entry: UnknownRecord): UnknownRecord | "missing" | undefined {
   if (entry.checkpoint === true) {
@@ -171,10 +208,11 @@ export function readResult(base: string, launch: Launch): Result | undefined {
   if (!result) {
     return;
   }
-  const pending = result.accountingPending;
-  if (pending === undefined) {
+  const accounting = accountingState(result);
+  if (accounting.kind !== "pending") {
     return result;
   }
+  const { pending } = accounting;
   let contributions;
   try {
     contributions = childUsage(launch, new Set(pending.baseline), pending.terminalCandidate);
@@ -183,7 +221,14 @@ export function readResult(base: string, launch: Launch): Result | undefined {
     return result;
   }
   const { accountingPending: _pending, accountingError: _error, ...execution } = result;
-  const repaired = { ...execution, terminalEntryId: pending.terminalCandidate, contributions };
+  const repaired = {
+    ...execution,
+    ...accountingFields({
+      kind: "verified",
+      terminalEntryId: pending.terminalCandidate,
+      contributions,
+    }),
+  };
   write(path.join(runDirectory(base, launch.id), "result.json"), repaired);
   return repaired;
 }

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;
+}