@fitchmultz/pi-subagents 0.52.20 → 0.52.21

package/dist/pi-intercom/connection.js

@@ -12,7 +12,6 @@ export class IntercomConnection {
     reconnectTimer = null;
     startupTimer = null;
     connecting = null;
-    connectingGeneration = null;
     attempt = 0;
     lifecycle;
     config;
@@ -294,8 +293,8 @@ export class IntercomConnection {
         if (!ctx || generation !== this.lifecycle.generation) {
             throw new Error("Intercom shutting down");
         }
-        if (this.connecting && this.connectingGeneration === generation) {
-            return this.connecting;
+        if (this.connecting?.generation === generation) {
+            return this.connecting.task;
         }
         if (this.client?.isConnected() === true) {
             return this.client;
@@ -307,8 +306,7 @@ export class IntercomConnection {
         this.clearReconnect();
         // Publish ownership before registration, which can synchronously invoke subscribers.
         const attempt = Promise.resolve().then(() => this.connect(ctx, generation, sessionId));
-        this.connecting = attempt;
-        this.connectingGeneration = generation;
+        this.connecting = { task: attempt, generation };
         return await this.finishAttempt(attempt, ctx, generation);
     }
     async finishAttempt(attempt, ctx, generation) {
@@ -321,9 +319,8 @@ export class IntercomConnection {
             throw error;
         }
         finally {
-            if (this.connecting === attempt) {
+            if (this.connecting?.task === attempt) {
                 this.connecting = null;
-                this.connectingGeneration = null;
             }
             if (retry) {
                 this.scheduleReconnect();
@@ -334,7 +331,7 @@ export class IntercomConnection {
         this.clearTimers();
         this.cancelWakes();
         // The bounded launcher attempt is joined before socket shutdown.
-        await Promise.allSettled([this.connecting]);
+        await Promise.allSettled([this.connecting?.task]);
         if (this.client) {
             await this.client.disconnect();
             this.client = null;

package/dist/pi-intercom/inbound-journal.js

@@ -150,13 +150,16 @@ export class InboundJournal {
                 if (pending.stage === "queued" &&
                     pending.from.id === entry.from.id &&
                     pending.message.threadId === entry.message.threadId) {
-                    this.consume(pending.message.id);
-                    this.replies.markReplied(pending.message.id);
+                    this.supersede(pending.message.id);
                 }
             }
         }
         this.pending.set(entry.message.id, entry);
     }
+    supersede(id) {
+        this.consume(id);
+        this.replies.markReplied(id);
+    }
     setStage(entry, stage) {
         if (entry.stage === stage) {
             return;

package/dist/shared/journal-frames.js

@@ -5,9 +5,7 @@ import { errorDescription, isRecord } from "./unknown.js";
 export class JournalFrames {
     projection;
     decoder = new TextDecoder("utf8", { fatal: true });
-    error;
-    failed = false;
-    nonblank = false;
+    state = { kind: "blank" };
     start;
     offset;
     policy;
@@ -29,21 +27,21 @@ export class JournalFrames {
         return new JsonProjection(this.select, this.options.stringChunk);
     }
     part(bytes) {
-        if (!this.nonblank && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
-            this.nonblank = true;
+        if (this.state.kind === "invalid") {
+            return;
         }
-        if (!this.failed) {
-            try {
-                this.projection.write(this.decoder.decode(bytes, { stream: true }));
-            }
-            catch (error) {
-                this.failed = true;
-                this.error = error;
-            }
+        if (this.state.kind === "blank" && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
+            this.state = { kind: "reading" };
+        }
+        try {
+            this.projection.write(this.decoder.decode(bytes, { stream: true }));
+        }
+        catch (error) {
+            this.state = { kind: "invalid", error };
         }
     }
     finishRecord(end) {
-        if (!this.nonblank || this.failed) {
+        if (this.state.kind !== "reading") {
             return undefined;
         }
         try {
@@ -55,17 +53,16 @@ export class JournalFrames {
             return { value, start: this.start, end };
         }
         catch (error) {
-            this.failed = true;
-            this.error = error;
+            this.state = { kind: "invalid", error };
             return undefined;
         }
     }
     commit(end) {
         const start = this.start;
         const record = this.finishRecord(end);
-        const failed = this.failed;
-        const error = this.error;
-        if (failed && this.policy !== "inspect") {
+        const state = this.state;
+        if (state.kind === "invalid" && this.policy !== "inspect") {
+            const { error } = state;
             throw new SyntaxError(`Invalid JSONL record at byte ${start}: ${errorDescription(error)}`, {
                 cause: error,
             });
@@ -73,10 +70,8 @@ export class JournalFrames {
         this.start = end;
         this.projection = this.newProjection();
         this.decoder = new TextDecoder("utf8", { fatal: true });
-        this.error = undefined;
-        this.failed = false;
-        this.nonblank = false;
-        if (!failed && record) {
+        this.state = { kind: "blank" };
+        if (record) {
             this.record(record);
         }
     }
@@ -93,7 +88,7 @@ export class JournalFrames {
     }
     finish() {
         if (this.requireNewline) {
-            if (this.policy === "strict" && this.nonblank) {
+            if (this.policy === "strict" && this.state.kind !== "blank") {
                 throw new SyntaxError(`Unpublished JSONL record at byte ${this.start}: newline required`);
             }
         }

package/docs/development.md

@@ -86,6 +86,12 @@ npm and attached to the matching GitHub release.
 
 ## Isolation and safety
 
+Actor command admission keeps execution separate from native session activity.
+Execution is either idle or running with one launch and task. A stopping actor
+admits no new Run work. Run, Steer and Stop payloads are action-specific;
+guidance always carries a prompt and new Stops always name the actor token.
+Historical unbound Stops remain readable and receive stale admission receipts.
+
 Parent attachment keeps one binding through detached, waiting, attaching and
 attached phases. The existing shutdown signal closes the owner. Managed
 readiness can attach only its own still-current waiting binding; shutdown joins

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.52.20",
+  "version": "0.52.21",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/src/agent/contracts.ts

@@ -110,14 +110,23 @@ export type AccountingState =
       readonly error: string;
       readonly terminalEntryId: string | undefined;
     };
-export const commandSchema = Type.Object({
+export const commandMetadataSchema = Type.Object({
   id: Type.String(),
   runId: Type.String(),
   action: Type.Union([Type.Literal("run"), Type.Literal("steer"), Type.Literal("stop")]),
-  prompt: Type.Optional(Type.String()),
-  actorToken: Type.Optional(Type.String()),
   createdAt: Type.Number(),
 });
+const commandFields = Type.Omit(commandMetadataSchema, ["action"]).properties;
+export const commandSchema = Type.Union([
+  Type.Object({ ...commandFields, action: Type.Literal("run") }),
+  Type.Object({ ...commandFields, action: Type.Literal("steer"), prompt: Type.String() }),
+  Type.Object({
+    ...commandFields,
+    action: Type.Literal("stop"),
+    // Historical unbound Stops parse but cannot target any current actor.
+    actorToken: Type.Optional(Type.String()),
+  }),
+]);
 export type Command = Static<typeof commandSchema>;
 export const successorSchema = Type.Object({ id: Type.String() });
 /** Authority to restore exact working state, valid only after the named actor has exited. */

package/src/agent/index.ts

@@ -8,8 +8,8 @@ import type {
   ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import {
-  actor,
-  alive,
+  inspectActorClaim,
+  possiblyLive,
   ensureActor,
   ownIdentity,
   parkFailure,
@@ -324,7 +324,7 @@ class AgentRuntime {
       executionCwd: executionCwd(this.pi, context),
     });
     this.checkMain();
-    enqueue(this.base, launch, "run");
+    enqueue(this.base, launch, { action: "run" });
     await ensureActor(this.base, launch, this.shutdown.signal);
     return renderReceipt(this.base, launch, this.ctx, {
       receipt: "launch",
@@ -352,14 +352,14 @@ class AgentRuntime {
     return;
   }
   private async retryContinuation(launch: Launch, input: RunsInput) {
-    const identity = actor(this.base, launch);
+    const claim = inspectActorClaim(this.base, launch);
     const command = read(
       path.join(conversation(this.base, launch), "commands", `${launch.id}.json`),
       commandSchema,
     );
     if (
       input.prompt !== launch.prompt ||
-      (identity && alive(identity)) ||
+      possiblyLive(claim) ||
       command?.id !== launch.id ||
       command.runId !== launch.id ||
       command.action !== "run"
@@ -383,9 +383,9 @@ class AgentRuntime {
     if (completed === "pending") {
       return this.retryContinuation(launch, input);
     }
-    const identity = actor(this.base, launch);
-    if (!completed && identity && alive(identity)) {
-      const command = enqueue(this.base, launch, "steer", { prompt: input.prompt });
+    const claim = completed ? undefined : inspectActorClaim(this.base, launch);
+    if (possiblyLive(claim)) {
+      const command = enqueue(this.base, launch, { action: "steer", prompt: input.prompt });
       return renderReceipt(this.base, launch, this.ctx, {
         receipt: "guidance",
         command,
@@ -400,7 +400,7 @@ class AgentRuntime {
       });
     }
     // Retain successor claims on ambiguous after-launch failures: no replay.
-    enqueue(this.base, next, "run");
+    enqueue(this.base, next, { action: "run" });
     await ensureActor(this.base, next, this.shutdown.signal);
     return renderReceipt(this.base, next, this.ctx, { receipt: "continuation" });
   }
@@ -417,7 +417,7 @@ class AgentRuntime {
     });
     if (created) {
       // The durable adoption claim survives ambiguous after-launch failures.
-      enqueue(this.base, launch, "run");
+      enqueue(this.base, launch, { action: "run" });
       await ensureActor(this.base, launch, this.shutdown.signal);
     }
     return renderReceipt(this.base, launch, this.ctx, {

package/src/agent/legacy.ts

@@ -7,7 +7,7 @@ import { journalStamp } from "../shared/native-journal.ts";
 import { receiptId } from "./receipts.ts";
 import { resolveTempRootDir } from "../shared/types.ts";
 import { isRecord } from "../shared/unknown.ts";
-import { release, isHeld, type Completion } from "./notifications.ts";
+import { release, completionDelivery, type Completion } from "./notifications.ts";
 import { missing } from "./storage.ts";
 
 interface LegacyInput {
@@ -135,13 +135,13 @@ function published(ctx: ExtensionContext, input: LegacyInput): "file" | "memory"
 }
 function notification(ctx: ExtensionContext, input: LegacyInput): Completion | undefined {
   const identity = `legacy:${input.id}:${input.key}`;
-  const where = published(ctx, input);
-  if (where !== undefined) {
+  const state = completionDelivery(input.owner, identity, published(ctx, input));
+  if (state.kind === "published") {
     release(input.owner, identity);
     // Retire only an unchanged recovery input whose receipt is LF-published in the session file.
     // An in-memory receipt stops redelivery but never removes the saved input.
     if (
-      where === "file" &&
+      state.where === "file" &&
       journalStamp(fs.lstatSync(input.file, { bigint: true })) === input.stamp &&
       fs.readFileSync(input.file, "utf8") === input.raw
     ) {
@@ -149,7 +149,7 @@ function notification(ctx: ExtensionContext, input: LegacyInput): Completion | u
     }
     return;
   }
-  if (isHeld(input.owner, identity)) {
+  if (state.kind === "held") {
     return;
   }
   return {

package/src/agent/notifications.ts

@@ -28,19 +28,29 @@ function queuedAdmissions(): Set<string> {
   return queued;
 }
 const admissions = queuedAdmissions();
-function hold(owner: string, id: string): boolean {
-  const key = `${owner}/${id}`;
-  if (admissions.has(key)) {
-    return false;
-  }
-  admissions.add(key);
-  return true;
+function hold(owner: string, id: string): void {
+  admissions.add(`${owner}/${id}`);
 }
 export function release(owner: string, id: string): void {
   admissions.delete(`${owner}/${id}`);
 }
-export function isHeld(owner: string, id: string): boolean {
-  return admissions.has(`${owner}/${id}`);
+type DeliveryDecision =
+  | { readonly kind: "published"; readonly where: "file" | "memory" }
+  | { readonly kind: "held" | "deliverable" };
+
+/** Canonical result readers establish availability before deciding delivery. */
+function deliveryDecision(receipt: "file" | "memory" | undefined, held: boolean): DeliveryDecision {
+  return receipt === undefined
+    ? { kind: held ? "held" : "deliverable" }
+    : { kind: "published", where: receipt };
+}
+
+export function completionDelivery(
+  owner: string,
+  id: string,
+  receipt: "file" | "memory" | undefined,
+): DeliveryDecision {
+  return deliveryDecision(receipt, admissions.has(`${owner}/${id}`));
 }
 /** Returns whether any admission was released for reconciliation. */
 export function settle(owner: string, pending: boolean): boolean {
@@ -243,14 +253,24 @@ export function notifications(ctx: ExtensionContext, base: string, owner: string
   const awaited = new Set<string>();
   const runs = completed(base, owner, awaited);
   const receipts = runs.length === 0 ? undefined : completionReceipts(ctx.sessionManager, owner);
+  const where = ctx.sessionManager.getSessionFile() === undefined ? "memory" : "file";
   for (const run of runs) {
-    const key = `${owner}/${run.id}`;
-    if (receipts?.get(run.id) !== undefined) {
-      admissions.delete(key);
-      continue;
+    const state = completionDelivery(
+      owner,
+      run.id,
+      receipts?.get(run.id) === undefined ? undefined : where,
+    );
+    switch (state.kind) {
+      case "published":
+        release(owner, run.id);
+        continue;
+      case "held":
+        continue;
+      case "deliverable":
+        break;
     }
-    const loaded = admissions.has(key) ? undefined : (run.loaded ?? load(base, run.id, owner));
-    if (loaded?.result !== undefined) {
+    const loaded = run.loaded ?? load(base, run.id, owner);
+    if (loaded.result !== undefined) {
       notices.push(notification(base, loaded.launch, loaded.result));
     }
   }

package/src/agent/parent-check.ts

@@ -0,0 +1,40 @@
+import { attachmentSchema } from "./contracts.ts";
+import { observeAlive, published } from "./process.ts";
+import { read } from "./storage.ts";
+
+/** A parent liveness verdict acts only while its check and attachment generation are current. */
+export class ParentCheck {
+  private current?: object | undefined;
+  check(file: string, detached: () => void): Promise<void> {
+    if (this.current !== undefined) {
+      return Promise.resolve();
+    }
+    const attachment = published(file, read(file, attachmentSchema));
+    if (attachment === undefined || !attachment.attached) {
+      detached();
+      return Promise.resolve();
+    }
+    const check = {};
+    this.current = check;
+    const settle = async () => {
+      try {
+        const [live] = await observeAlive([attachment]);
+        if (
+          this.current === check &&
+          live !== true &&
+          read(file, attachmentSchema)?.generation === attachment.generation
+        ) {
+          detached();
+        }
+      } finally {
+        if (this.current === check) {
+          this.current = undefined;
+        }
+      }
+    };
+    return settle();
+  }
+  cancel(): void {
+    this.current = undefined;
+  }
+}

package/src/agent/process.ts

@@ -14,7 +14,6 @@ import {
 import { agentObservationSocketPath } from "../pi-intercom/broker/paths.ts";
 import { hasErrorCode } from "../shared/unknown.ts";
 import {
-  attachmentSchema,
   parkedSchema,
   processSchema,
   wakeFailureSchema,
@@ -49,12 +48,19 @@ function probe(identity: ClaimedProcess): boolean | undefined {
   }
   return identity.identity === "unverified" ? true : undefined;
 }
+function presence(identity: ClaimedProcess): "live" | "exited" | "uncertain" {
+  const probed = probe(identity);
+  if (probed !== undefined) {
+    return probed ? "uncertain" : "exited";
+  }
+  if (readChildProcessIdentity(identity.pid) === identity.identity) {
+    return "live";
+  }
+  return replaced(identity) ? "exited" : "uncertain";
+}
 export function alive(identity: ClaimedProcess): boolean {
-  // Only a proven different birth disproves a live PID; ambiguous identities stay possibly owned.
-  return (
-    probe(identity) ??
-    (readChildProcessIdentity(identity.pid) === identity.identity || !replaced(identity))
-  );
+  // Uncertain identity remains possibly owned; only death/replacement authorizes reuse.
+  return presence(identity) !== "exited";
 }
 /** Routine `alive` without waiting on `ps`; signals still use the synchronous proof. */
 export async function observeAlive(identities: readonly ClaimedProcess[]): Promise<boolean[]> {
@@ -68,51 +74,6 @@ export async function observeAlive(identities: readonly ClaimedProcess[]): Promi
   }
   return verdicts;
 }
-/**
- * A child's routine parent check, one observation at a time. A dead parent detaches the child
- * only while its check is current and the attachment generation is unchanged: a newer parent
- * may adopt the child meanwhile.
- */
-export class ParentCheck {
-  private current?: object | undefined;
-  /**
-   * Reads the attachment synchronously, so an unreadable one still fails the caller at once.
-   * Missing or released attachments detach immediately; a check in flight makes this a no-op.
-   */
-  check(file: string, detached: () => void): Promise<void> {
-    if (this.current !== undefined) {
-      return Promise.resolve();
-    }
-    const attachment = published(file, read(file, attachmentSchema));
-    if (attachment === undefined || !attachment.attached) {
-      detached();
-      return Promise.resolve();
-    }
-    const check = {};
-    this.current = check;
-    const settle = async () => {
-      try {
-        const [live] = await observeAlive([attachment]);
-        if (
-          this.current === check &&
-          live !== true &&
-          read(file, attachmentSchema)?.generation === attachment.generation
-        ) {
-          detached();
-        }
-      } finally {
-        if (this.current === check) {
-          this.current = undefined;
-        }
-      }
-    };
-    return settle();
-  }
-  /** A check settling later no longer acts. */
-  cancel(): void {
-    this.current = undefined;
-  }
-}
 function replaced(identity: ClaimedProcess): boolean {
   return (
     identity.identity !== "unverified" &&
@@ -132,6 +93,42 @@ export function actor(base: string, launch: Launch): OwnedProcess | undefined {
   const file = path.join(conversation(base, launch), "actor.lock", "process.json");
   return published(file, read(file, processSchema));
 }
+type ActorClaim =
+  | { readonly kind: "absent" | "launcher-only"; readonly process: undefined }
+  | { readonly kind: "actor-live" | "actor-exited"; readonly process: OwnedProcess }
+  | { readonly kind: "uncertain"; readonly process: OwnedProcess | undefined };
+
+export function possiblyLive(claim: ActorClaim | undefined): boolean {
+  return (
+    claim?.kind === "actor-live" || (claim?.kind === "uncertain" && claim.process !== undefined)
+  );
+}
+
+/** Launcher claims do not prove actor identity; shell ownership is checked separately. */
+export function inspectActorClaim(base: string, launch: Launch): ActorClaim {
+  const process = actor(base, launch);
+  if (process !== undefined) {
+    switch (presence(process)) {
+      case "live":
+        return { kind: "actor-live", process };
+      case "exited":
+        return { kind: "actor-exited", process };
+      case "uncertain":
+        return { kind: "uncertain", process };
+    }
+  }
+  const lock = path.join(conversation(base, launch), "actor.lock");
+  if (!fs.existsSync(lock)) {
+    return { kind: "absent", process: undefined };
+  }
+  return {
+    kind:
+      read(path.join(lock, "claim.json"), processSchema) === undefined
+        ? "uncertain"
+        : "launcher-only",
+    process: undefined,
+  };
+}
 function childEnvironment(launch: Launch): NodeJS.ProcessEnv {
   const env = { ...process.env };
   for (const key of Object.keys(env)) {
@@ -299,8 +296,9 @@ export async function ensureActor(
   await awaitStopping(dir, actor(base, launch), signal);
   signal?.throwIfAborted();
   // Another parallel tool may replace the claim while this invocation yields.
-  const existing = actor(base, launch);
-  if (existing && alive(existing)) {
+  const claim = inspectActorClaim(base, launch);
+  const existing = claim.process;
+  if (possiblyLive(claim)) {
     return;
   }
   parkFailure(base, launch, existing);
@@ -438,13 +436,13 @@ export function requestStop(
       return false;
     }
   };
-  const identity = actor(base, launch);
+  const identity = inspectActorClaim(base, launch).process;
   const targets = identity ? [identity, ...shells(base, launch, identity.token)] : [];
   // Interactive Stop validates the whole set; shutdown reports and skips only ambiguous targets.
   const live = targets.filter((target) => attempt(() => verifyProcess(target)));
   const command =
     identity && live.includes(identity)
-      ? enqueue(base, launch, "stop", { actorToken: identity.token })
+      ? enqueue(base, launch, { action: "stop", actorToken: identity.token })
       : undefined;
   if (identity && live.length > 0) {
     write(path.join(conversation(base, launch), `stopping-${identity.token}.json`), {