@nklisch/pi-enhanced 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.2.3
+
+### Fixed
+
+- Rebundle `@nklisch/pi-plugins` 0.4.2 with clean child-session shutdown and serialized, Pi-idle-aware subagent resume.
+
+## v0.2.2
+
+### Fixed
+
+- Point the bundled FFF compatibility resource at its extension entrypoint instead of its source directory, preventing Pi from trying to load the finder lifecycle helper as an extension.
+
 ## v0.2.1
 
 ### Fixed

package/node_modules/@nklisch/pi-fff-compat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-fff-compat",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Fast FFF-backed file search through Pi-native find/grep semantics — glob-only file lookup and exact regex/literal grep with no fuzzy fallback.",
   "author": {
     "name": "nklisch"
@@ -30,7 +30,7 @@
   ],
   "pi": {
     "extensions": [
-      "./extensions"
+      "./extensions/fff-compat-search.ts"
     ]
   },
   "private": false,

package/node_modules/@nklisch/pi-plugins/README.md

@@ -62,7 +62,7 @@ Marketplace-derived network access is origin-authorized and DNS-pinned. Credenti
 The current production package pins:
 
 - `@nklisch/pi-mcp-adapter@2.21.0-nklisch.1`
-- `@nklisch/pi-subagents@18.1.0-nklisch.2`
+- `@nklisch/pi-subagents@18.1.0-nklisch.3`
 
 Executable dependencies are checked against their declared package shape before import: exact name and version, license, engine and peer ranges, required exports, and declared Pi resources. The MCP and subagent packages are transitive dependencies: one top-level `pi install npm:@nklisch/pi-plugins` installs and activates both through verified wrappers, so they do not need separate `pi install` entries. The bundled subagent loader reuses Pi's already-loaded coding-agent, AI, and TUI module identities rather than installing a second Pi runtime tree. Package, API, runtime-range, or behavioral drift makes the affected capability unavailable rather than partially activating it. Subagent lifecycle conformance remains a separate qualification contract.
 

package/node_modules/@nklisch/pi-plugins/dist/runtime/subagents/pi-subagents-package.js

@@ -7,7 +7,7 @@ import { createJiti } from "jiti/static";
 import { probePublishedPackage, } from "../published-package-receipt.js";
 export const PI_SUBAGENTS_RECEIPT = Object.freeze({
     packageName: "@nklisch/pi-subagents",
-    version: "18.1.0-nklisch.2",
+    version: "18.1.0-nklisch.3",
     license: "MIT",
     nodeEngine: ">=22",
     piPeerRange: ">=0.80.5",

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [18.1.0-nklisch.3] - 2026-08-24
+
+### Fixed
+
+- Emit and await child `session_shutdown` before disposing `AgentSession`, so child extensions cancel detached work before Pi invalidates their contexts.
+- Serialize resume admission and wait through aborted-turn wind-down and Pi's authoritative idle boundary, preventing false `Agent is already processing` failures and concurrent resume races.
+
 ## [18.1.0-nklisch.2] - 2026-08-23
 
 ### Fixed

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/README.md

@@ -268,9 +268,11 @@ Excess agents are automatically queued and start as running agents complete. The
 
 Foreground agents bypass the queue — they block the parent anyway. Completion nudges are held while the parent is running and flushed at the parent run boundary, preventing a pulled result from also arriving as a duplicate notification.
 
+Resume requests are serialized per retained session. A second request while a turn is genuinely active gets a deterministic busy result; after an abort or extension-driven continuation, resume waits for both the prior invocation and Pi's authoritative idle boundary instead of racing `AgentSession.prompt()`. Session teardown likewise emits and awaits `session_shutdown` before Pi revokes child extension contexts, allowing child-owned processes and timers to stop cleanly.
+
 ## Persistent Settings
 
-Runtime tuning values set via `/subagents:settings` persist across pi restarts. Terminal records remain available for the whole parent session. Their heavy live sessions are released after the consumed or unconsumed retention window; the result and persisted transcript pointer remain available.
+Runtime tuning values set via `/subagents:settings` persist across pi restarts. Terminal records remain available for the whole parent session. Their heavy live sessions are released after the consumed or unconsumed retention window; the result and persisted transcript pointer remain available, but a released session cannot resume without starting a new subagent. A completion notification, foreground result, or `get_subagent_result` collection marks a result consumed, so the shorter consumed window normally governs after delivery.
 Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults.

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/architecture.md

@@ -126,9 +126,11 @@ classDiagram
         +subscribeToUpdates(fn): unsub | undefined
         +messages: readonly unknown[]
         +effectiveThinkingLevel: ThinkingLevel
+        -executionInFlight: boolean
+        -resumeReserved: boolean
         +completeRun(result)
         +failRun(err)
-        +disposeSession()
+        +disposeSession(): Promise~void~
     }
 
     class SubagentState {
@@ -216,10 +218,12 @@ stateDiagram-v2
     running --> stopped : max turns reached
     running --> steered : steer message injected
     steered --> running : continues with message
-    completed --> running : resetForResume
-    stopped --> running : resetForResume
-    error --> running : resetForResume
-    aborted --> running : resetForResume
+    completed --> resume_wait : reserve resume
+    stopped --> resume_wait : reserve after abort
+    error --> resume_wait : reserve resume
+    aborted --> resume_wait : reserve resume
+    resume_wait --> running : prior execution settled + Pi idle
+    resume_wait --> stopped : abort resume wait
     completed --> [*]
     error --> [*]
     aborted --> [*]
@@ -233,11 +237,13 @@ stateDiagram-v2
 ```
 
 Note: `markStopped` always succeeds regardless of current status.
-Other terminal transitions guard against overwriting `stopped` — once an agent is stopped, only `resetForResume` can return it to `running`.
+Other terminal transitions guard against overwriting `stopped` — once an agent is stopped, only an admitted resume can return it to `running`.
 
-Terminal outcomes also carry orthogonal consumption state. Foreground delivery, `get_subagent_result`, and a queued completion notification mark the outcome consumed. Records remain available for the parent session; only their heavy live child sessions are released after the configured consumed or unconsumed retention window. Released records keep their result and persisted transcript pointer but cannot resume.
+Resume admission is a record-owned lease. A genuinely running or already-reserved record rejects a second resume before reaching Pi. A stopped record may still own a winding-down prompt, and Pi may still be finishing post-run continuation after the domain result looks terminal; the lease therefore spans the prior execution promise and Pi's authoritative `agent_settled`/`isIdle` boundary. Retention, abort, result waiting, and manager shutdown all treat the lease as active.
 
-Completion notifications are held while the parent agent run is active and flushed on `agent_settled`, rechecking consumption before enqueueing a follow-up. Child session creation shares the parent model runtime and leaves extension-tool registration open; a denylist removes disallowed built-ins and recursive orchestration tools across registry refreshes.
+Terminal outcomes also carry orthogonal consumption state. Foreground delivery, `get_subagent_result`, and a queued completion notification mark the outcome consumed. Records remain available for the parent session; only their heavy live child sessions are released after the configured consumed or unconsumed retention window. Released records keep their result and persisted transcript pointer but cannot resume. Release detaches the session synchronously before awaiting teardown, so it cannot race a new resume.
+
+Completion notifications are held while the parent agent run is active and flushed on `agent_settled`, rechecking consumption before enqueueing a follow-up. Child session creation shares the parent model runtime and leaves extension-tool registration open; a denylist removes disallowed built-ins and recursive orchestration tools across registry refreshes. Child teardown mirrors Pi's managed root lifecycle: it emits and awaits `session_shutdown` before `AgentSession.dispose()` revokes extension contexts, then publishes the child `disposed` event.
 
 ## Execution flow
 
@@ -391,7 +397,7 @@ They declare this package as an optional peer dependency and use dynamic import
 - `SubagentManager` — spawn, abort, resume, collection management, observer wiring.
 - `ConcurrencyLimiter` — background admission gate: schedules run thunks FIFO against a configurable concurrency limit.
 - `createSubagentSession` — assembly factory: session creation and extension binding; returns a born-complete `SubagentSession`.
-- `SubagentSession` — the born-complete child session: drives the turn loop (`runTurnLoop`/`resumeTurnLoop`), steers, and disposes (firing `disposed` at true session disposal, so resume executions are registry-detected).
+- `SubagentSession` — the born-complete child session: drives turn loops, exposes Pi's idle boundary, steers, and performs idempotent asynchronous teardown (`session_shutdown` → `AgentSession.dispose()` → child `disposed`).
 - `child-lifecycle` — publishes the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) on `pi.events`.
   Reactive consumers subscribe: `@gotgenes/pi-permission-system` registers each child session on `session-created` and unregisters it on `disposed`.
   This replaced the former outbound `permission-bridge` (#261, [ADR-0002]) — the core no longer looks up a named consumer.

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-subagents",
-  "version": "18.1.0-nklisch.2",
+  "version": "18.1.0-nklisch.3",
   "type": "module",
   "exports": {
     ".": {

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/handlers/lifecycle.ts

@@ -9,9 +9,9 @@ import type { SessionContext } from "#src/types";
 
 /** Narrow manager interface — only the methods lifecycle handlers call. */
 export interface LifecycleManager {
-  clearCompleted(): void;
+  clearCompleted(): Promise<void>;
   abortAll(): void;
-  dispose(): void;
+  dispose(): Promise<void>;
 }
 
 /** Narrow runtime interface — only the methods lifecycle handlers call. */
@@ -37,13 +37,13 @@ export class SessionLifecycleHandler {
     private readonly unpublishService: () => void,
   ) {}
 
-  handleSessionStart(_event: unknown, ctx: unknown): void {
+  async handleSessionStart(_event: unknown, ctx: unknown): Promise<void> {
     this.runtime.setSessionContext(ctx as SessionContext);
-    this.manager.clearCompleted();
+    await this.manager.clearCompleted();
   }
 
-  handleSessionBeforeSwitch(): void {
-    this.manager.clearCompleted();
+  async handleSessionBeforeSwitch(): Promise<void> {
+    await this.manager.clearCompleted();
   }
 
   // Cleanup order matters:
@@ -52,12 +52,11 @@ export class SessionLifecycleHandler {
   // 3. Dispose notifications — prevent terminal transitions from enqueueing follow-ups
   // 4. Abort all agents — stop running and queued work
   // 5. Dispose manager — final cleanup
-  handleSessionShutdown(): Promise<void> {
+  async handleSessionShutdown(): Promise<void> {
     this.unpublishService();
     this.runtime.clearSessionContext();
     this.disposeNotifications();
     this.manager.abortAll();
-    this.manager.dispose();
-    return Promise.resolve();
+    await this.manager.dispose();
   }
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/create-subagent-session.ts

@@ -242,9 +242,10 @@ export async function createSubagentSession(
     // are included in the post-bind active set.
     applyRecursionGuard(session);
   } catch (err) {
-    // Binding failed after session-created — dispose (emit disposed +
-    // session.dispose()) before rethrowing so registration is never leaked.
-    subagentSession.dispose();
+    // Binding failed after session-created — shut extensions down, dispose the
+    // SDK session, and unregister the child before rethrowing. Awaiting keeps a
+    // partially-bound extension from escaping with detached work.
+    await subagentSession.dispose();
     throw err;
   }
 

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/subagent-manager.ts

@@ -8,7 +8,7 @@
 
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
-import { debugLog, runSafely } from "#src/debug";
+import { debugLog, runDetached, runSafely } from "#src/debug";
 import type { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import {
@@ -89,6 +89,7 @@ export class SubagentManager {
   private getRunConfig?: () => RunConfig;
   private _workspaceProvider?: WorkspaceProvider;
   private readonly lifecycleInterceptors = new LifecycleInterceptorRegistry();
+  private disposalPromise?: Promise<void>;
 
   /** The registered workspace provider, or undefined when none is registered. */
   get workspaceProvider(): WorkspaceProvider | undefined {
@@ -105,11 +106,7 @@ export class SubagentManager {
     // Timer callbacks sit outside Pi's extension runner, so a malformed setting
     // or disposal failure must remain diagnostic rather than escape into Node.
     this.cleanupInterval = setInterval(() => {
-      try {
-        this.cleanup();
-      } catch (error) {
-        debugLog("retention cleanup", error);
-      }
+      runDetached("retention cleanup", () => this.cleanup());
     }, 60_000);
     this.cleanupInterval.unref();
   }
@@ -293,17 +290,20 @@ export class SubagentManager {
   }
 
   /** Dispose a record's session and remove it from the map. */
-  private removeRecord(id: string, record: Subagent): void {
-    record.disposeSession();
+  private async removeRecord(id: string, record: Subagent): Promise<void> {
+    // Remove first so no caller can acquire a record while its extensions are
+    // shutting down asynchronously.
     this.agents.delete(id);
+    await record.disposeSession();
   }
 
-  private cleanup() {
+  private async cleanup(): Promise<void> {
     const now = Date.now();
     const config = this.getRunConfig?.();
     const consumedMinutes = config?.consumedSessionRetentionMinutes ?? 10;
     const unconsumedMinutes = config?.unconsumedSessionRetentionMinutes ?? 720;
 
+    const releases: Promise<void>[] = [];
     for (const record of this.agents.values()) {
       if (record.isActive() || !record.isSessionReady()) continue;
       const anchor = record.consumed
@@ -314,33 +314,33 @@ export class SubagentManager {
       if (anchor + retentionMinutes * 60_000 > now) continue;
       // Keep the lightweight terminal record and result for the whole parent
       // session; only release the heavy in-memory child session.
-      record.releaseSession();
+      releases.push(record.releaseSession());
     }
+    await Promise.all(releases);
   }
 
   /**
    * Remove all completed/stopped/errored records immediately.
    * Called on session start/switch so tasks from a prior session don't persist.
    */
-  clearCompleted(): void {
+  async clearCompleted(): Promise<void> {
+    const disposals: Promise<void>[] = [];
     for (const [id, record] of this.agents) {
-      if (record.status === "running" || record.status === "queued") continue;
+      if (record.isActive()) continue;
       try {
         this.observer?.onSubagentCleared?.(record);
       } catch (err) {
         debugLog("onSubagentCleared observer", err);
       }
-      this.removeRecord(id, record);
+      disposals.push(this.removeRecord(id, record));
     }
-
+    await Promise.all(disposals);
   }
 
   /** Whether any agents are still running or queued. */
   // fallow-ignore-next-line unused-class-member
   hasRunning(): boolean {
-    return [...this.agents.values()].some(
-      r => r.status === "running" || r.status === "queued",
-    );
+    return [...this.agents.values()].some((record) => record.isActive());
   }
 
   /** Abort all running and queued agents immediately. */
@@ -376,22 +376,31 @@ export class SubagentManager {
   /** Promises of all running/queued agents that have one. */
   private pendingPromises(): Promise<void>[] {
     return [...this.agents.values()]
-      .filter(r => r.status === "running" || r.status === "queued")
+      .filter((record) => record.isActive())
       .map(r => r.promise)
       .filter((p): p is Promise<void> => p != null);
   }
 
-  dispose() {
+  dispose(): Promise<void> {
+    this.disposalPromise ??= this.disposeOnce();
+    return this.disposalPromise;
+  }
+
+  private async disposeOnce(): Promise<void> {
     clearInterval(this.cleanupInterval);
     // Lifecycle callbacks observe the shutdown signal before their registration
-    // disposer runs. Existing no-provider teardown stays synchronous. Consume
-    // async disposer failures because manager disposal is intentionally sync.
-    void this.lifecycleInterceptors.dispose().catch((error) => debugLog("lifecycle interceptor shutdown", error));
-    // Drop pending thunks
-    this.limiter.clear();
-    for (const record of this.agents.values()) {
-      record.disposeSession();
+    // disposer runs. Await their finalizers before child extension teardown.
+    try {
+      await this.lifecycleInterceptors.dispose();
+    } catch (error) {
+      debugLog("lifecycle interceptor shutdown", error);
     }
+
+    // Drop pending thunks and make every record unreachable before awaiting
+    // extension shutdown. No new resume can race teardown from this point.
+    this.limiter.clear();
+    const records = [...this.agents.values()];
     this.agents.clear();
+    await Promise.all(records.map((record) => record.disposeSession()));
   }
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/subagent-session.ts

@@ -74,7 +74,7 @@ export interface SubagentSessionMeta {
  * One child AgentSession plus its turn-driving and teardown — born complete.
  */
 export class SubagentSession {
-  private disposed = false;
+  private disposalPromise?: Promise<void>;
 
   constructor(
     private readonly _session: AgentSession,
@@ -309,6 +309,52 @@ export class SubagentSession {
     });
   }
 
+  /** Whether Pi has fully settled the child, including post-run continuation. */
+  get isIdle(): boolean {
+    return this._session.isIdle;
+  }
+
+  /**
+   * Wait for Pi's authoritative idle boundary before starting another prompt.
+   * A record can already look terminal while AgentSession is still finishing an
+   * extension-driven continuation, so domain status alone is insufficient.
+   */
+  async waitUntilIdle(signal?: AbortSignal): Promise<void> {
+    if (this._session.isIdle) return;
+    signal?.throwIfAborted();
+
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      let unsubscribe: () => void = () => {};
+      const cleanup = (): void => {
+        signal?.removeEventListener("abort", onAbort);
+        unsubscribe();
+      };
+      const finish = (): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve();
+      };
+      const onAbort = (): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(signal?.reason ?? new Error("Resume wait aborted"));
+      };
+
+      unsubscribe = this._session.subscribe((event: AgentSessionEvent) => {
+        if (event.type === "agent_settled" || this._session.isIdle) finish();
+      });
+      signal?.addEventListener("abort", onAbort, { once: true });
+
+      // Close the check/subscribe race: Pi may have settled between the first
+      // isIdle read and listener registration.
+      if (this._session.isIdle) finish();
+      else if (signal?.aborted) onAbort();
+    });
+  }
+
   /** Deliver a steer to the live session. */
   async steer(message: string): Promise<void> {
     await this._session.steer(message);
@@ -349,14 +395,32 @@ export class SubagentSession {
     return this._session.getToolDefinition(name);
   }
 
-  /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
-  dispose(): void {
-    if (this.disposed) return;
-    this.disposed = true;
+  /**
+   * Tear down the child session exactly once.
+   *
+   * AgentSession.dispose() revokes extension contexts immediately but does not
+   * emit the extension lifecycle event. Child-owned extensions need the same
+   * awaited shutdown boundary as root-session replacement so they can cancel
+   * detached work before their Pi API is invalidated.
+   */
+  dispose(): Promise<void> {
+    this.disposalPromise ??= this.disposeOnce();
+    return this.disposalPromise;
+  }
+
+  private async disposeOnce(): Promise<void> {
+    try {
+      await this._session.extensionRunner.emit({
+        type: "session_shutdown",
+        reason: "quit",
+      });
+    } catch (error) {
+      // A faulty extension must not prevent the SDK session from being revoked.
+      debugLog("child extension session_shutdown", error);
+    }
 
     try {
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
-      this._session.dispose?.();
+      this._session.dispose();
     } catch (error) {
       debugLog("child session dispose", error);
     }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/subagent.ts

@@ -55,6 +55,14 @@ export type SteerOutcome =
 	| { kind: "buffered" }
 	| { kind: "rejected"; status: SubagentStatus };
 
+/** A second prompt was requested while this record already owned an execution. */
+export class SubagentBusyError extends Error {
+	constructor(agentId: string) {
+		super(`Subagent "${agentId}" is still processing a turn. Wait for it to settle before resuming.`);
+		this.name = "SubagentBusyError";
+	}
+}
+
 /**
  * The execution machinery a Subagent needs to run. A single mandatory
  * collaborator: production (SubagentManager.spawn) always supplies it, so run()
@@ -140,6 +148,11 @@ export class Subagent {
 	private _effectiveThinkingLevel: ThinkingLevel;
 	private readonly listeners = new RunListeners();
 	private readonly workspaceBracket: WorkspaceBracket;
+	/** True while run()/runResume() owns the child prompt boundary. */
+	private executionInFlight = false;
+	/** Synchronous admission lease spanning wind-down, Pi idle, and resume. */
+	private resumeReserved = false;
+	private pendingResumeAbort?: AbortController;
 
 	subagentSession?: SubagentSession;
 	private releasedOutputFile?: string;
@@ -167,7 +180,7 @@ export class Subagent {
 	}
 
 	isActive(): boolean {
-		return this.status === "queued" || this.status === "running";
+		return this.status === "queued" || this.status === "running" || this.resumeReserved;
 	}
 
 	isRunning(): boolean {
@@ -263,6 +276,7 @@ export class Subagent {
 	 * captured internally).
 	 */
 	async run(): Promise<void> {
+		this.executionInFlight = true;
 		this.markRunning(Date.now());
 		try {
 			// Observer callbacks are extension-owned sinks, not part of the agent's
@@ -322,6 +336,8 @@ export class Subagent {
 			// One outer failure path guarantees terminal state, listener release,
 			// workspace cleanup, and the manager's completion funnel.
 			this.failRun(err);
+		} finally {
+			this.executionInFlight = false;
 		}
 	}
 
@@ -371,8 +387,65 @@ export class Subagent {
 					: "Subagent not configured for resume — missing session",
 			));
 		}
-		this._promise = this.runResume(subagentSession, prompt, signal);
-		return this._promise;
+		if (this.status === "queued" || this.status === "running" || this.resumeReserved) {
+			return Promise.reject(new SubagentBusyError(this.id));
+		}
+
+		// Reserve synchronously before the first await. This closes both the
+		// concurrent-resume race and retention's release-while-waiting race.
+		this.resumeReserved = true;
+		const previousExecution = this.executionInFlight ? this._promise : undefined;
+		const resumeAbort = new AbortController();
+		this.pendingResumeAbort = resumeAbort;
+		const resumed = this.resumeWhenReady(
+			subagentSession,
+			previousExecution,
+			prompt,
+			resumeAbort,
+			signal,
+		);
+		this._promise = resumed;
+		return resumed;
+	}
+
+	private async resumeWhenReady(
+		subagentSession: SubagentSession,
+		previousExecution: Promise<void> | undefined,
+		prompt: string,
+		resumeAbort: AbortController,
+		signal?: AbortSignal,
+	): Promise<void> {
+		const waitSignal = signal
+			? AbortSignal.any([resumeAbort.signal, signal])
+			: resumeAbort.signal;
+		let started = false;
+		try {
+			// abort() marks a record stopped before AgentSession.prompt() necessarily
+			// settles. Wait for both the record-owned invocation and Pi's stronger
+			// idle boundary instead of racing a new prompt into the old one.
+			if (previousExecution) await previousExecution;
+			waitSignal.throwIfAborted();
+			await subagentSession.waitUntilIdle(waitSignal);
+			waitSignal.throwIfAborted();
+			if (this.subagentSession !== subagentSession) {
+				throw new Error("Subagent session was released while waiting to resume");
+			}
+
+			started = true;
+			this.executionInFlight = true;
+			this.resetForResume(Date.now(), resumeAbort);
+			await this.runResume(subagentSession, prompt, signal);
+		} catch (error) {
+			if (waitSignal.aborted) this.markStopped();
+			else this.markError(error);
+			if (!started) {
+				runSafely("subagent onResumedFinished observer", () => this.execution.observer?.onResumedFinished?.(this));
+			}
+		} finally {
+			if (started) this.executionInFlight = false;
+			if (this.pendingResumeAbort === resumeAbort) this.pendingResumeAbort = undefined;
+			this.resumeReserved = false;
+		}
 	}
 
 	private async runResume(
@@ -380,7 +453,6 @@ export class Subagent {
 		prompt: string,
 		signal?: AbortSignal,
 	): Promise<void> {
-		this.resetForResume(Date.now());
 		const executionSignal = signal
 			? AbortSignal.any([this.abortController.signal, signal])
 			: this.abortController.signal;
@@ -420,7 +492,7 @@ export class Subagent {
 	/** Wait for the current queued, running, or resumed execution without cancelling it. */
 	async waitUntilSettled(signal: AbortSignal): Promise<void> {
 		const run = this._promise;
-		if (!run || !this.isActive() || signal.aborted) return;
+		if (!run || (!this.executionInFlight && !this.resumeReserved) || signal.aborted) return;
 		await settleOrAbort(run, signal);
 	}
 
@@ -535,8 +607,9 @@ export class Subagent {
 	 * then no-ops on the queued-status guard.
 	 */
 	abort(): boolean {
-		if (this.status !== "running") return false;
+		if (this.status !== "running" && !this.resumeReserved) return false;
 		this.abortController.abort();
+		this.pendingResumeAbort?.abort();
 		this.markStopped();
 		return true;
 	}
@@ -561,8 +634,8 @@ export class Subagent {
 	}
 
 	/** Reset for resume: running status, new startedAt, clear completedAt/result/error/listeners. */
-	resetForResume(startedAt: number): void {
-		this.abortController = new AbortController();
+	resetForResume(startedAt: number, controller = new AbortController()): void {
+		this.abortController = controller;
 		this.state.resetForResume(startedAt);
 		this.listeners.release();
 	}
@@ -598,18 +671,25 @@ export class Subagent {
 	}
 
 	/** Dispose the wrapped session, firing the `disposed` lifecycle event. */
-	disposeSession(): void {
-		this.subagentSession?.dispose();
+	async disposeSession(): Promise<void> {
+		const session = this.subagentSession;
+		if (!session) return;
+		// Detach first: callers must not admit a resume while asynchronous
+		// extension shutdown is in progress.
+		this.subagentSession = undefined;
+		await session.dispose();
 	}
 
 	/** Release heavy session state while preserving the transcript pointer and record. */
-	releaseSession(): void {
+	async releaseSession(): Promise<void> {
 		const session = this.subagentSession;
 		if (!session) return;
 		this.releasedOutputFile = session.outputFile;
-		session.dispose();
+		// The record becomes non-resumable atomically at release admission, not
+		// after extension shutdown finishes.
 		this.subagentSession = undefined;
 		this._sessionReleased = true;
+		await session.dispose();
 	}
 
 	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/agent-tool.ts

@@ -7,6 +7,7 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import { THINKING_LEVELS_DESCRIPTION } from "#src/config/thinking-levels";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import { SubagentBusyError } from "#src/lifecycle/subagent";
 import { spawnBackground } from "#src/tools/background-spawner";
 import { runForeground } from "#src/tools/foreground-runner";
 import { buildAgentGuidelines, buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
@@ -97,11 +98,17 @@ export class AgentTool {
 						: `Agent "${params.resume}" has no active session to resume.`,
 				);
 			}
-			const record = await this.manager.resume(
-				params.resume as string,
-				params.prompt as string,
-				signal ?? new AbortController().signal,
-			);
+			let record: Subagent | undefined;
+			try {
+				record = await this.manager.resume(
+					params.resume as string,
+					params.prompt as string,
+					signal ?? new AbortController().signal,
+				);
+			} catch (error) {
+				if (error instanceof SubagentBusyError) return textResult(error.message);
+				throw error;
+			}
 			if (!record) {
 				return textResult(`Failed to resume agent "${params.resume}".`);
 			}

package/node_modules/@nklisch/pi-plugins/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-plugins",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": false,
   "description": "Native marketplace and plugin lifecycle management for Pi, with Claude Code and Codex compatibility.",
   "license": "MIT",
@@ -68,7 +68,7 @@
   ],
   "dependencies": {
     "@nklisch/pi-mcp-adapter": "2.21.0-nklisch.1",
-    "@nklisch/pi-subagents": "18.1.0-nklisch.2",
+    "@nklisch/pi-subagents": "18.1.0-nklisch.3",
     "jiti": "2.7.0",
     "semver": "7.8.1",
     "smol-toml": "^1.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-enhanced",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Pi, enhanced — one install for nklisch's full harness: policy-gated command review, plugin marketplace, subagents, background tasks, research tools, search, model modes, and a curated UX set.",
   "author": {
     "name": "nklisch"
@@ -29,7 +29,7 @@
   "pi": {
     "extensions": [
       "./node_modules/@nklisch/pi-conveniences/extensions",
-      "./node_modules/@nklisch/pi-fff-compat/extensions",
+      "./node_modules/@nklisch/pi-fff-compat/extensions/fff-compat-search.ts",
       "./node_modules/@nklisch/pi-model-modes/extensions/index.ts",
       "./node_modules/@nklisch/pi-background-tasks/extensions/background-tasks.ts",
       "./node_modules/@nklisch/pi-plugins/dist/pi/production-subagents-extension.js",

package/test/verify-bundle.mjs

@@ -34,6 +34,14 @@ const declared = [
 ].map((p) => p.replace(/^\.\//, ""));
 
 const failures = [];
+const fffCompatEntrypoint = "./node_modules/@nklisch/pi-fff-compat/extensions/fff-compat-search.ts";
+if (!manifest.pi.extensions.includes(fffCompatEntrypoint)) {
+  failures.push(`${fffCompatEntrypoint} (FFF compatibility extension entrypoint not declared)`);
+}
+if (manifest.pi.extensions.includes("./node_modules/@nklisch/pi-fff-compat/extensions")) {
+  failures.push("node_modules/@nklisch/pi-fff-compat/extensions (directory would load non-extension helpers)");
+}
+
 for (const declaredPath of declared) {
   // A declared path may be a directory, a single file, or a SKILL.md path.
   // It is satisfied when the tarball contains the path itself or anything