@nklisch/pi-enhanced 0.2.2 → 0.2.4

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

@@ -0,0 +1,289 @@
+import { lstat, mkdir, readFile, readdir, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { assertNoSymlinks, assertSafeName, resolveContainedExistingPath } from "./paths.js";
+import { SUPPORTED_HOOK_EVENTS } from "./types.js";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function diagnostic(scope, error) {
+    return Object.freeze({ scope, message: error instanceof Error ? error.message : String(error), cause: error });
+}
+async function optionalJson(path) {
+    try {
+        return { value: JSON.parse(await readFile(path, "utf8")) };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        return { error };
+    }
+}
+async function isDirectory(path) {
+    try {
+        const stat = await lstat(path);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function isFile(path) {
+    try {
+        const stat = await lstat(path);
+        return stat.isFile() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function containsSkillFile(root) {
+    if (!await isDirectory(root))
+        return false;
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            continue;
+        const child = join(root, entry.name);
+        if (entry.isFile() && entry.name === "SKILL.md")
+            return true;
+        if (entry.isDirectory() && !entry.name.startsWith(".") && await containsSkillFile(child))
+            return true;
+    }
+    return false;
+}
+function timeoutMilliseconds(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return 10_000;
+    // Claude hook metadata expresses timeout in seconds. Keep a practical upper
+    // bound so a malformed catalog cannot make Pi wait indefinitely.
+    return Math.min(Math.max(value * 1_000, 100), 10 * 60 * 1_000);
+}
+function hookEvent(value) {
+    return SUPPORTED_HOOK_EVENTS.includes(value);
+}
+function parseHooks(value, scope) {
+    const diagnostics = [];
+    if (!record(value))
+        throw new Error("hooks document must be an object");
+    const declaration = record(value.hooks) ? value.hooks : value;
+    const hooks = [];
+    for (const [eventName, groupsValue] of Object.entries(declaration)) {
+        if (!hookEvent(eventName)) {
+            diagnostics.push(diagnostic(`${scope}.${eventName}`, new Error(`unsupported hook event: ${eventName}`)));
+            continue;
+        }
+        const groups = Array.isArray(groupsValue) ? groupsValue : [groupsValue];
+        for (const [groupIndex, groupValue] of groups.entries()) {
+            if (!record(groupValue)) {
+                diagnostics.push(diagnostic(`${scope}.${eventName}[${groupIndex}]`, new Error("hook group must be an object")));
+                continue;
+            }
+            const matcher = typeof groupValue.matcher === "string" ? groupValue.matcher : undefined;
+            const commands = Array.isArray(groupValue.hooks) ? groupValue.hooks : [groupValue.hooks];
+            for (const [commandIndex, commandValue] of commands.entries()) {
+                if (!record(commandValue) || commandValue.type !== "command" || typeof commandValue.command !== "string" || commandValue.command.trim().length === 0) {
+                    diagnostics.push(diagnostic(`${scope}.${eventName}[${groupIndex}].hooks[${commandIndex}]`, new Error("only non-empty command hooks are supported")));
+                    continue;
+                }
+                hooks.push(Object.freeze({
+                    event: eventName,
+                    ...(matcher === undefined ? {} : { matcher }),
+                    command: commandValue.command,
+                    timeoutMs: timeoutMilliseconds(commandValue.timeout),
+                }));
+            }
+        }
+    }
+    return { hooks, diagnostics };
+}
+async function declaredPath(root, value, scope) {
+    if (typeof value !== "string")
+        return undefined;
+    return resolveContainedExistingPath(root, value, scope);
+}
+async function readManifest(root, relativePath, diagnostics) {
+    const path = join(root, relativePath);
+    const result = await optionalJson(path);
+    if (result.error !== undefined) {
+        diagnostics.push(diagnostic(`${relativePath}`, result.error));
+        return undefined;
+    }
+    if (result.value === undefined)
+        return undefined;
+    if (!record(result.value)) {
+        diagnostics.push(diagnostic(relativePath, new Error("plugin manifest must be an object")));
+        return undefined;
+    }
+    return result.value;
+}
+async function discoverPlugin(root, marketplace, name, data) {
+    const diagnostics = [];
+    try {
+        await assertNoSymlinks(root);
+    }
+    catch (error) {
+        diagnostics.push(diagnostic("bundle", error));
+        return Object.freeze({
+            info: Object.freeze({ marketplace, name, root, data, enabled: false }),
+            skillPaths: [],
+            hooks: [],
+            diagnostics: Object.freeze(diagnostics),
+        });
+    }
+    const receiptResult = await optionalJson(join(root, ".pi-plugin.json"));
+    if (receiptResult.error !== undefined)
+        diagnostics.push(diagnostic(".pi-plugin.json", receiptResult.error));
+    const receipt = record(receiptResult.value) ? Object.freeze({ ...receiptResult.value }) : undefined;
+    const disabled = await isFile(join(root, ".disabled"));
+    const info = Object.freeze({
+        marketplace,
+        name,
+        root,
+        data,
+        enabled: !disabled,
+        ...(receipt === undefined ? {} : { receipt }),
+    });
+    if (disabled)
+        return Object.freeze({ info, skillPaths: [], hooks: [], diagnostics: Object.freeze(diagnostics) });
+    const skillPaths = [];
+    if (await isFile(join(root, "SKILL.md")))
+        skillPaths.push(root);
+    const skillsRoot = join(root, "skills");
+    if (await containsSkillFile(skillsRoot))
+        skillPaths.push(skillsRoot);
+    const manifests = [];
+    for (const relativePath of [".claude-plugin/plugin.json", ".codex-plugin/plugin.json"]) {
+        const manifest = await readManifest(root, relativePath, diagnostics);
+        if (manifest !== undefined)
+            manifests.push(manifest);
+    }
+    const hookPaths = new Set();
+    const conventionalHooks = join(root, "hooks/hooks.json");
+    if (await isFile(conventionalHooks))
+        hookPaths.add(conventionalHooks);
+    for (const manifest of manifests) {
+        if (typeof manifest.hooks === "string") {
+            try {
+                hookPaths.add(await declaredPath(root, manifest.hooks, "manifest hooks path") ?? "");
+            }
+            catch (error) {
+                diagnostics.push(diagnostic("manifest hooks path", error));
+            }
+        }
+    }
+    const hooks = [];
+    for (const path of hookPaths) {
+        if (path.length === 0)
+            continue;
+        const result = await optionalJson(path);
+        if (result.error !== undefined) {
+            diagnostics.push(diagnostic(path, result.error));
+            continue;
+        }
+        if (result.value === undefined)
+            continue;
+        try {
+            const parsed = parseHooks(result.value, path);
+            hooks.push(...parsed.hooks);
+            diagnostics.push(...parsed.diagnostics);
+        }
+        catch (error) {
+            diagnostics.push(diagnostic(path, error));
+        }
+    }
+    const mcpDocuments = [];
+    const conventionalMcp = join(root, ".mcp.json");
+    if (await isFile(conventionalMcp))
+        mcpDocuments.push(conventionalMcp);
+    for (const manifest of manifests) {
+        const declaration = manifest.mcpServers ?? manifest.mcp;
+        if (typeof declaration === "string") {
+            try {
+                const path = await declaredPath(root, declaration, "manifest MCP path");
+                if (path !== undefined)
+                    mcpDocuments.push(path);
+            }
+            catch (error) {
+                diagnostics.push(diagnostic("manifest MCP path", error));
+            }
+        }
+        else if (record(declaration)) {
+            mcpDocuments.push(declaration);
+        }
+    }
+    const mcpServers = {};
+    for (const document of mcpDocuments) {
+        let value = document;
+        if (typeof document === "string") {
+            const result = await optionalJson(document);
+            if (result.error !== undefined) {
+                diagnostics.push(diagnostic(document, result.error));
+                continue;
+            }
+            value = result.value;
+        }
+        if (!record(value)) {
+            diagnostics.push(diagnostic("MCP", new Error("MCP document must be an object")));
+            continue;
+        }
+        const servers = record(value.mcpServers) ? value.mcpServers : value;
+        for (const [serverName, server] of Object.entries(servers)) {
+            if (!record(server)) {
+                diagnostics.push(diagnostic(`MCP.${serverName}`, new Error("MCP server declaration must be an object")));
+                continue;
+            }
+            mcpServers[serverName] = server;
+        }
+    }
+    return Object.freeze({
+        info,
+        skillPaths: Object.freeze(skillPaths),
+        hooks: Object.freeze(hooks),
+        ...(Object.keys(mcpServers).length === 0 ? {} : { mcp: Object.freeze(mcpServers) }),
+        diagnostics: Object.freeze(diagnostics),
+    });
+}
+export async function scanInstalledPlugins(paths) {
+    const plugins = [];
+    const diagnostics = [];
+    let marketplaces = [];
+    try {
+        marketplaces = (await readdir(paths.plugins, { withFileTypes: true })).filter((item) => item.isDirectory() && !item.isSymbolicLink() && !item.name.startsWith(".")).map((item) => item.name);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            diagnostics.push(diagnostic("plugins", error));
+    }
+    for (const marketplace of marketplaces.sort()) {
+        let pluginEntries;
+        try {
+            pluginEntries = await readdir(join(paths.plugins, marketplace), { withFileTypes: true });
+        }
+        catch (error) {
+            diagnostics.push(diagnostic(`plugins/${marketplace}`, error));
+            continue;
+        }
+        for (const entry of pluginEntries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name.startsWith(".") || !entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            try {
+                const name = assertSafeName(entry.name, "plugin name");
+                const root = await realpath(join(paths.plugins, marketplace, name));
+                const data = join(paths.data, marketplace, name);
+                await mkdir(data, { recursive: true });
+                const discovered = await discoverPlugin(root, marketplace, name, data);
+                plugins.push(discovered);
+                diagnostics.push(...discovered.diagnostics);
+            }
+            catch (error) {
+                diagnostics.push(diagnostic(`${marketplace}/${entry.name}`, error));
+            }
+        }
+    }
+    const skillPaths = [...new Set(plugins.filter((plugin) => plugin.info.enabled).flatMap((plugin) => plugin.skillPaths))];
+    return Object.freeze({
+        plugins: Object.freeze(plugins),
+        skillPaths: Object.freeze(skillPaths),
+        diagnostics: Object.freeze(diagnostics),
+    });
+}
+//# sourceMappingURL=runtime-discovery.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-discovery.js","sourceRoot":"","sources":["../src/runtime-discovery.ts"],"names":[],"mappings":"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"}

package/node_modules/@nklisch/pi-plugins/dist/types.d.ts

@@ -0,0 +1,113 @@
+export type MarketplaceSourceKind = "github" | "git" | "local";
+export interface MarketplaceSource {
+    readonly kind: MarketplaceSourceKind;
+    readonly value: string;
+    readonly ref?: string;
+}
+export type PluginSource = Readonly<{
+    kind: "local";
+    path: string;
+}> | Readonly<{
+    kind: "git" | "git-subdir";
+    url: string;
+    path?: string;
+    ref?: string;
+}>;
+export interface CatalogPlugin {
+    readonly name: string;
+    readonly source: PluginSource;
+    readonly description?: string;
+    readonly version?: string;
+    readonly raw: Readonly<Record<string, unknown>> | string;
+}
+export interface MarketplaceCatalog {
+    readonly name: string;
+    readonly plugins: readonly CatalogPlugin[];
+    readonly sources: readonly string[];
+    readonly diagnostics?: readonly PluginDiagnostic[];
+}
+export interface PluginDiagnostic {
+    readonly scope: string;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+export interface MarketplaceInfo {
+    readonly name: string;
+    readonly source: MarketplaceSource;
+    readonly root: string;
+    readonly checkout: string;
+}
+export interface InstalledPluginInfo {
+    readonly marketplace: string;
+    readonly name: string;
+    readonly root: string;
+    readonly data: string;
+    readonly enabled: boolean;
+    readonly receipt?: Readonly<Record<string, unknown>>;
+}
+export interface PluginHookCommand {
+    readonly event: SupportedHookEvent;
+    readonly matcher?: string;
+    readonly command: string;
+    readonly timeoutMs: number;
+}
+export declare const SUPPORTED_HOOK_EVENTS: readonly ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PreCompact", "PostCompact", "Stop"];
+export type SupportedHookEvent = (typeof SUPPORTED_HOOK_EVENTS)[number];
+export interface DiscoveredPlugin {
+    readonly info: InstalledPluginInfo;
+    readonly skillPaths: readonly string[];
+    readonly hooks: readonly PluginHookCommand[];
+    readonly mcp?: Readonly<Record<string, unknown>>;
+    readonly diagnostics: readonly PluginDiagnostic[];
+}
+export interface RuntimeSnapshot {
+    readonly plugins: readonly DiscoveredPlugin[];
+    readonly skillPaths: readonly string[];
+    readonly diagnostics: readonly PluginDiagnostic[];
+}
+export interface PluginHostPaths extends Readonly<PluginHostPathsShape> {
+}
+export interface PluginHostPathsShape {
+    readonly agentDir: string;
+    readonly hostRoot: string;
+    readonly marketplaces: string;
+    readonly plugins: string;
+    readonly data: string;
+}
+export interface AddMarketplaceOptions {
+    readonly ref?: string;
+}
+export interface PluginMutationOptions {
+    readonly preserveDisabled?: boolean;
+}
+export interface PluginHost {
+    readonly paths: PluginHostPaths;
+    addMarketplace(source: string, options?: AddMarketplaceOptions): Promise<MarketplaceInfo>;
+    listMarketplaces(): Promise<readonly MarketplaceInfo[]>;
+    refreshMarketplace(name: string): Promise<MarketplaceInfo>;
+    removeMarketplace(name: string): Promise<void>;
+    browseMarketplace(name: string): Promise<MarketplaceCatalog>;
+    listInstalled(): Promise<readonly InstalledPluginInfo[]>;
+    installPlugin(marketplace: string, plugin: string): Promise<InstalledPluginInfo>;
+    updatePlugin(marketplace: string, plugin: string): Promise<InstalledPluginInfo>;
+    enablePlugin(marketplace: string, plugin: string): Promise<InstalledPluginInfo>;
+    disablePlugin(marketplace: string, plugin: string): Promise<InstalledPluginInfo>;
+    removePlugin(marketplace: string, plugin: string, deleteData?: boolean): Promise<void>;
+    scanRuntime(): Promise<RuntimeSnapshot>;
+    buildMcpConfig(snapshot?: RuntimeSnapshot): Promise<Readonly<{
+        mcpServers: Readonly<Record<string, unknown>>;
+    }>>;
+}
+export type HookOutput = Readonly<{
+    additionalContext?: string;
+    block?: boolean;
+    reason?: string;
+    continue?: boolean;
+}>;
+export interface HookExecutionResult {
+    readonly ok: boolean;
+    readonly output?: HookOutput;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly error?: unknown;
+}

package/node_modules/@nklisch/pi-plugins/dist/types.js

@@ -0,0 +1,12 @@
+export const SUPPORTED_HOOK_EVENTS = [
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PreCompact",
+    "PostCompact",
+    "Stop",
+];
+//# sourceMappingURL=types.js.map

package/node_modules/@nklisch/pi-plugins/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwDA,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,cAAc;IACd,YAAY;IACZ,kBAAkB;IAClB,YAAY;IACZ,aAAa;IACb,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,MAAM;CACE,CAAC"}

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