@nklisch/pi-enhanced 0.1.2 → 0.1.4

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

@@ -27,29 +27,11 @@ import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
-/**
- * A lightweight snapshot of a subagent evicted by the 10-minute cleanup sweep.
- *
- * The sweep frees the heavy in-memory session (its message history included);
- * this descriptor retains only the fields the session navigator needs to label
- * the agent in the picker, plus the persisted `outputFile` to source its
- * transcript from disk. Carries no messages, so memory stays bounded.
- */
-export interface EvictedSubagent {
-  readonly id: string;
-  readonly type: SubagentType;
-  readonly description: string;
-  readonly status: SubagentStatus;
-  readonly startedAt: number;
-  readonly completedAt: number | undefined;
-  readonly toolUses: number;
-  readonly outputFile: string;
-}
-
 /** Observer interface for agent lifecycle notifications. */
 export interface SubagentManagerObserver {
   onSubagentStarted(record: Subagent): void;
   onSubagentCompleted(record: Subagent): void;
+  onSubagentResumed?(record: Subagent): void;
   onSubagentCompacted(record: Subagent, info: CompactionInfo): void;
   /** Fires synchronously after a background agent record is created (before run). */
   onSubagentCreated(record: Subagent): void;
@@ -95,8 +77,6 @@ export interface AgentSpawnConfig {
 
 export class SubagentManager {
   private agents = new Map<string, Subagent>();
-  /** Descriptors of agents removed by the cleanup sweep, keyed by id — navigable from disk. */
-  private readonly evicted = new Map<string, EvictedSubagent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: SubagentManagerObserver;
   private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
@@ -117,7 +97,7 @@ export class SubagentManager {
     this.baseCwd = options.baseCwd;
     this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
-    // Cleanup completed agents after 10 minutes (but keep sessions for resume)
+    // Periodically release heavy terminal sessions according to retention policy.
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
     this.cleanupInterval.unref();
   }
@@ -160,6 +140,9 @@ export class SubagentManager {
           try { this.observer?.onSubagentCompleted(agent); } catch (err) { debugLog("onSubagentCompleted observer", err); }
         }
       },
+      onResumedFinished: (agent) => {
+        try { this.observer?.onSubagentResumed?.(agent); } catch (err) { debugLog("onSubagentResumed observer", err); }
+      },
       onCompacted: (agent, info) => {
         this.observer?.onSubagentCompacted(agent, info);
       },
@@ -271,19 +254,14 @@ export class SubagentManager {
     );
   }
 
-  /** Descriptors of agents evicted by the cleanup sweep, most recent first. */
-  listEvicted(): EvictedSubagent[] {
-    return [...this.evicted.values()].sort((a, b) => b.startedAt - a.startedAt);
-  }
-
   abort(id: string): boolean {
     const record = this.agents.get(id);
     if (!record) return false;
 
-    // A queued agent has not started; mark it stopped. Its scheduled thunk
-    // becomes a no-op (status guard) when its slot finally opens.
+    // A queued agent has not started; terminate it through the observer funnel.
+    // Its scheduled thunk becomes a no-op when its slot eventually opens.
     if (record.status === "queued") {
-      record.markStopped();
+      record.stopQueued();
       return true;
     }
 
@@ -297,14 +275,22 @@ export class SubagentManager {
   }
 
   private cleanup() {
-    const cutoff = Date.now() - 10 * 60_000;
-    for (const [id, record] of this.agents) {
-      if (record.status === "running" || record.status === "queued") continue;
-      if ((record.completedAt ?? 0) >= cutoff) continue;
-      // Retain a navigable descriptor before freeing the heavy session. Only an
-      // agent with a persisted file can be sourced from disk after eviction.
-      if (record.outputFile) this.evicted.set(id, toEvictedSubagent(record, record.outputFile));
-      this.removeRecord(id, record);
+    const now = Date.now();
+    const config = this.getRunConfig?.();
+    const consumedMinutes = config?.consumedSessionRetentionMinutes ?? 10;
+    const unconsumedMinutes = config?.unconsumedSessionRetentionMinutes ?? 720;
+
+    for (const record of this.agents.values()) {
+      if (record.isActive() || !record.isSessionReady()) continue;
+      const anchor = record.consumed
+        ? record.consumedAt ?? record.completedAt
+        : record.completedAt;
+      if (anchor == null) continue;
+      const retentionMinutes = record.consumed ? consumedMinutes : unconsumedMinutes;
+      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();
     }
   }
 
@@ -317,8 +303,7 @@ export class SubagentManager {
       if (record.status === "running" || record.status === "queued") continue;
       this.removeRecord(id, record);
     }
-    // Evicted descriptors belong to the session that swept them — a new session starts empty.
-    this.evicted.clear();
+
   }
 
   /** Whether any agents are still running or queued. */
@@ -335,7 +320,7 @@ export class SubagentManager {
     let count = 0;
     for (const record of this.agents.values()) {
       if (record.status === "queued") {
-        record.markStopped();
+        record.stopQueued();
         count++;
       } else if (record.abort()) {
         count++;
@@ -378,20 +363,5 @@ export class SubagentManager {
       record.disposeSession();
     }
     this.agents.clear();
-    this.evicted.clear();
   }
 }
-
-/** Capture an evicted agent's navigable fields from its record. */
-function toEvictedSubagent(record: Subagent, outputFile: string): EvictedSubagent {
-  return {
-    id: record.id,
-    type: record.type,
-    description: record.description,
-    status: record.status,
-    startedAt: record.startedAt,
-    completedAt: record.completedAt,
-    toolUses: record.toolUses,
-    outputFile,
-  };
-}

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

@@ -29,6 +29,8 @@ import type { SessionMessage } from "#src/types";
 /** Outcome of one turn loop. */
 export interface TurnLoopResult {
   responseText: string;
+  /** Normally-resolved provider failure from the final assistant turn. */
+  failure?: string;
   /** True if the agent was hard-aborted (max turns + grace exceeded). */
   aborted: boolean;
   /** True if the agent was steered to wrap up (soft turn limit) but finished in time. */
@@ -121,6 +123,7 @@ export class SubagentSession {
       }
     });
 
+    const startIndex = session.messages.length;
     const collector = collectResponseText(session);
     const cleanupAbort = forwardAbortSignal(session, opts.signal);
 
@@ -135,13 +138,19 @@ export class SubagentSession {
         // published immediately after prompt resolution and before extraction.
         await session.prompt(effectivePrompt);
         this.publishCompleted(aborted, softLimitReached);
-        const responseText = collector.getText().trim() || getLastAssistantText(session);
-        return { responseText, aborted, steered: softLimitReached };
+        const responseText = collector.getText().trim() || getLastAssistantText(session, startIndex);
+        return {
+          responseText,
+          failure: finalTurnError(session, startIndex),
+          aborted,
+          steered: softLimitReached,
+        };
       }
       return await this.driveLifecycleTurns(
         effectivePrompt,
         opts.lifecycle,
-        () => collector.getText().trim() || getLastAssistantText(session),
+        () => collector.getText().trim() || getLastAssistantText(session, startIndex),
+        () => finalTurnError(session, startIndex),
         () => ({ aborted, steered: softLimitReached }),
       );
     } finally {
@@ -152,14 +161,21 @@ export class SubagentSession {
   }
 
   /** Re-prompt the same session (resume); preserves the released no-provider path. */
-  async resumeTurnLoop(prompt: string, signal?: AbortSignal): Promise<string> {
+  async resumeTurnLoop(
+    prompt: string,
+    signal?: AbortSignal,
+  ): Promise<{ text: string; failure?: string }> {
     const session = this._session;
+    const startIndex = session.messages.length;
     const collector = collectResponseText(session);
     const cleanupAbort = forwardAbortSignal(session, signal);
 
     try {
       await session.prompt(prompt);
-      return collector.getText().trim() || getLastAssistantText(session);
+      return {
+        text: collector.getText().trim() || getLastAssistantText(session, startIndex),
+        failure: finalTurnError(session, startIndex),
+      };
     } finally {
       collector.unsubscribe();
       cleanupAbort();
@@ -175,13 +191,15 @@ export class SubagentSession {
     signal: AbortSignal | undefined,
     lifecycle: SubagentTurnLifecycle,
   ): Promise<TurnLoopResult> {
+    const startIndex = this._session.messages.length;
     const collector = collectResponseText(this._session);
     const cleanupAbort = forwardAbortSignal(this._session, signal);
     try {
       return await this.driveLifecycleTurns(
         prompt,
         lifecycle,
-        () => collector.getText().trim() || getLastAssistantText(this._session),
+        () => collector.getText().trim() || getLastAssistantText(this._session, startIndex),
+        () => finalTurnError(this._session, startIndex),
         () => ({ aborted: false, steered: false }),
       );
     } finally {
@@ -194,6 +212,7 @@ export class SubagentSession {
     initialPrompt: string,
     lifecycle: SubagentTurnLifecycle,
     responseText: () => string,
+    failure: () => string | undefined,
     outcome: () => Readonly<{ aborted: boolean; steered: boolean }>,
   ): Promise<TurnLoopResult> {
     const start = await lifecycle.beforeStart(initialPrompt);
@@ -208,6 +227,10 @@ export class SubagentSession {
       await this._session.prompt(prompt);
       const turnOutcome = outcome();
       const proposedResult = responseText();
+      const turnFailure = failure();
+      if (turnFailure) {
+        return { responseText: proposedResult, failure: turnFailure, ...turnOutcome };
+      }
       const completion = await lifecycle.beforeComplete(
         proposedResult,
         toLifecycleOutcome(turnOutcome),
@@ -327,7 +350,7 @@ function toLifecycleOutcome(
 function collectResponseText(session: AgentSession) {
   let text = "";
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-    if (event.type === "message_start") {
+    if (event.type === "message_start" && event.message?.role === "assistant") {
       text = "";
     }
     if (
@@ -341,8 +364,8 @@ function collectResponseText(session: AgentSession) {
 }
 
 /** Get the last assistant text from the completed session history. */
-function getLastAssistantText(session: AgentSession): string {
-  for (let i = session.messages.length - 1; i >= 0; i--) {
+function getLastAssistantText(session: AgentSession, startIndex = 0): string {
+  for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
     const text = extractText(msg.content).trim();
@@ -351,6 +374,22 @@ function getLastAssistantText(session: AgentSession): string {
   return "";
 }
 
+/** Classify a normally-resolved failure from this invocation's final assistant turn. */
+function finalTurnError(session: AgentSession, startIndex = 0): string | undefined {
+  for (let i = session.messages.length - 1; i >= startIndex; i--) {
+    const msg = session.messages[i];
+    if (msg.role !== "assistant") continue;
+    if (msg.stopReason === "error") {
+      return msg.errorMessage?.trim() || "provider error with no output";
+    }
+    if (msg.stopReason === "length" && !extractText(msg.content).trim()) {
+      return "run hit the output token limit before producing any text";
+    }
+    return undefined;
+  }
+  return undefined;
+}
+
 /**
  * Wire an AbortSignal to abort a session.
  * Returns a cleanup function to remove the listener.

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

@@ -34,8 +34,12 @@ export interface SubagentStateInit {
 	status?: SubagentStatus;
 	result?: string;
 	error?: string;
+	/** Whether the limiter never admitted this agent. */
+	stoppedWhileQueued?: boolean;
 	startedAt?: number;
 	completedAt?: number;
+	/** Time the parent first collected the terminal outcome. */
+	consumedAt?: number;
 }
 
 export class SubagentState {
@@ -55,6 +59,13 @@ export class SubagentState {
 	private _completedAt?: number;
 	get completedAt(): number | undefined { return this._completedAt; }
 
+	private _stoppedWhileQueued: boolean;
+	get stoppedWhileQueued(): boolean { return this._stoppedWhileQueued; }
+
+	private _consumedAt?: number;
+	get consumedAt(): number | undefined { return this._consumedAt; }
+	get consumed(): boolean { return this._consumedAt != null; }
+
 	// Stats — accumulated via mutation methods, readable via getters
 	private _toolUses = 0;
 	get toolUses(): number { return this._toolUses; }
@@ -81,8 +92,10 @@ export class SubagentState {
 		this._status = init.status ?? "queued";
 		this._result = init.result;
 		this._error = init.error;
+		this._stoppedWhileQueued = init.stoppedWhileQueued ?? false;
 		this._startedAt = init.startedAt ?? Date.now();
 		this._completedAt = init.completedAt;
+		this._consumedAt = init.consumedAt;
 	}
 
 	/** Increment tool use count. Called by record-observer on tool_execution_end. */
@@ -177,19 +190,36 @@ export class SubagentState {
 	 * Always sets error (formatted) and completedAt (??=). Only changes status if not stopped.
 	 */
 	markError(error: unknown, completedAt?: number): void {
+		this.markFailed(error, undefined, completedAt);
+	}
+
+	/** Record a failure together with any partial output produced before it. */
+	markFailed(error: unknown, partialResult?: string, completedAt?: number): void {
 		this._error = error instanceof Error ? error.message : String(error);
+		this._result = partialResult?.trim() ? partialResult : undefined;
 		this._completedAt ??= completedAt ?? Date.now();
 		if (this._status !== "stopped") {
 			this._status = "error";
 		}
 	}
 
+	/** Record that the parent collected the outcome. Idempotent. */
+	markConsumed(at?: number): void {
+		this._consumedAt ??= at ?? Date.now();
+	}
+
 	/** Transition to stopped state. Always valid — no guard. */
 	markStopped(completedAt?: number): void {
 		this._status = "stopped";
 		this._completedAt = completedAt ?? Date.now();
 	}
 
+	/** Stop an agent before the limiter admitted it. */
+	stopQueued(completedAt?: number): void {
+		if (this._status === "queued") this._stoppedWhileQueued = true;
+		this.markStopped(completedAt);
+	}
+
 	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
 	resetForResume(startedAt: number): void {
 		this._status = "running";
@@ -197,5 +227,7 @@ export class SubagentState {
 		this._completedAt = undefined;
 		this._result = undefined;
 		this._error = undefined;
+		this._consumedAt = undefined;
+		this._stoppedWhileQueued = false;
 	}
 }

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

@@ -25,6 +25,7 @@ import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import { WorkspaceBracket } from "#src/lifecycle/workspace-bracket";
 import { subscribeSubagentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
+import { formatModelLabel } from "#src/session/model-label";
 import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SessionMessage, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Per-subagent lifecycle observer — created by SubagentManager for each spawn. */
@@ -33,8 +34,10 @@ export interface SubagentLifecycleObserver {
 	onStarted?(agent: Subagent): void;
 	/** Fires once the session is created — the subagent's subagentSession is now available. */
 	onSessionCreated?(agent: Subagent): void;
-	/** Fires once when the run completes or fails (for concurrency drain). */
+	/** Fires once when the initial run completes or fails (for concurrency drain). */
 	onRunFinished?(agent: Subagent): void;
+	/** Fires once when a resumed turn reaches a terminal state. */
+	onResumedFinished?(agent: Subagent): void;
 	/** Fires on compaction events during the run. */
 	onCompacted?(agent: Subagent, info: CompactionInfo): void;
 }
@@ -112,6 +115,9 @@ export class Subagent {
 	get error(): string | undefined { return this.state.error; }
 	get startedAt(): number { return this.state.startedAt; }
 	get completedAt(): number | undefined { return this.state.completedAt; }
+	get stoppedWhileQueued(): boolean { return this.state.stoppedWhileQueued; }
+	get consumedAt(): number | undefined { return this.state.consumedAt; }
+	get consumed(): boolean { return this.state.consumed; }
 	get toolUses(): number { return this.state.toolUses; }
 	get lifetimeUsage(): Readonly<LifetimeUsage> { return this.state.lifetimeUsage; }
 	get compactionCount(): number { return this.state.compactionCount; }
@@ -119,8 +125,10 @@ export class Subagent {
 	get activeTools(): ReadonlyMap<string, string> { return this.state.activeTools; }
 	get responseText(): string { return this.state.responseText; }
 	get maxTurns(): number | undefined { return this.execution.maxTurns; }
+	/** Exact effective model label used by every operator-facing status surface. */
+	get modelLabel(): string { return formatModelLabel(this.execution.model ?? this.execution.snapshot.model); }
 
-	readonly abortController: AbortController;
+	abortController: AbortController;
 	private _promise?: Promise<void>;
 	get promise(): Promise<void> | undefined { return this._promise; }
 
@@ -129,6 +137,9 @@ export class Subagent {
 	private readonly workspaceBracket: WorkspaceBracket;
 
 	subagentSession?: SubagentSession;
+	private releasedOutputFile?: string;
+	private _sessionReleased = false;
+	get sessionReleased(): boolean { return this._sessionReleased; }
 
 	// Steer buffer — messages queued before the session is ready
 	private _pendingSteers: string[] = [];
@@ -137,7 +148,7 @@ export class Subagent {
 
 	/** Path to the agent's session JSONL file, or undefined if not yet available. */
 	get outputFile(): string | undefined {
-		return this.subagentSession?.outputFile;
+		return this.subagentSession?.outputFile ?? this.releasedOutputFile;
 	}
 
 	/** The tool call ID that spawned this background agent, if any. */
@@ -150,6 +161,14 @@ export class Subagent {
 		return this.subagentSession != null;
 	}
 
+	isActive(): boolean {
+		return this.status === "queued" || this.status === "running";
+	}
+
+	isRunning(): boolean {
+		return this.status === "running";
+	}
+
 	/**
 	 * Steer a running agent, owning the non-running rejection rule.
 	 * Returns a `rejected` outcome (with the observed status) when the agent is
@@ -329,21 +348,35 @@ export class Subagent {
 	 *
 	 * Requires an existing SubagentSession (set when the original run created it).
 	 * The returned promise always resolves (errors are captured internally).
-	 * The parent signal flows straight through to resumeTurnLoop — resume does not
-	 * route through this.abortController.
+	 * Parent cancellation and manager abort both stop the resumed turn.
 	 */
-	async resume(prompt: string, signal?: AbortSignal): Promise<void> {
+	resume(prompt: string, signal?: AbortSignal): Promise<void> {
 		const subagentSession = this.subagentSession;
 		if (!subagentSession) {
-			throw new Error("Subagent not configured for resume — missing session");
+			return Promise.reject(new Error(
+				this.sessionReleased
+					? "Subagent session was released and can no longer be resumed"
+					: "Subagent not configured for resume — missing session",
+			));
 		}
+		this._promise = this.runResume(subagentSession, prompt, signal);
+		return this._promise;
+	}
 
+	private async runResume(
+		subagentSession: SubagentSession,
+		prompt: string,
+		signal?: AbortSignal,
+	): Promise<void> {
 		this.resetForResume(Date.now());
+		const executionSignal = signal
+			? AbortSignal.any([this.abortController.signal, signal])
+			: this.abortController.signal;
 		this.listeners.attachObserver(subscribeSubagentObserver(subagentSession, this.state, {
 			onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
 		}));
 
-		const lifecycle = this.createTurnLifecycle("resume", signal);
+		const lifecycle = this.createTurnLifecycle("resume", executionSignal);
 		try {
 			if (lifecycle) {
 				const result = await subagentSession.resumeLifecycleTurnLoop(
@@ -351,20 +384,31 @@ export class Subagent {
 					lifecycle.signal,
 					lifecycle,
 				);
-				if (result.aborted) this.markAborted(result.responseText);
+				if (result.failure) this.markFailed(result.failure, result.responseText);
+				else if (result.aborted) this.markAborted(result.responseText);
 				else if (result.steered) this.markSteered(result.responseText);
 				else this.markCompleted(result.responseText);
 			} else {
-				const responseText = await subagentSession.resumeTurnLoop(prompt, signal);
-				this.markCompleted(responseText);
+				const resumed = await subagentSession.resumeTurnLoop(prompt, executionSignal);
+				const outcome = typeof resumed === "string" ? { text: resumed } : resumed;
+				if (outcome.failure) this.markFailed(outcome.failure, outcome.text);
+				else this.markCompleted(outcome.text);
 			}
 		} catch (err) {
 			this.markError(err);
 		} finally {
 			this.listeners.release();
+			this.execution.observer?.onResumedFinished?.(this);
 		}
 	}
 
+	/** 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;
+		await settleOrAbort(run, signal);
+	}
+
 	/** Build a callback-only lifecycle bridge after the immutable child session exists. */
 	private createTurnLifecycle(
 		phase: "initial" | "resume",
@@ -449,11 +493,26 @@ export class Subagent {
 		this.state.markError(error, completedAt);
 	}
 
+	/** Record a provider failure and preserve any partial output. */
+	markFailed(error: unknown, partialResult?: string, completedAt?: number): void {
+		this.state.markFailed(error, partialResult, completedAt);
+	}
+
 	/** Transition to stopped state. Always valid — no guard. */
 	markStopped(completedAt?: number): void {
 		this.state.markStopped(completedAt);
 	}
 
+	markConsumed(at?: number): void {
+		this.state.markConsumed(at);
+	}
+
+	/** Stop a queued agent through the same terminal observer funnel as a run. */
+	stopQueued(): void {
+		this.state.stopQueued();
+		this.execution.observer?.onRunFinished?.(this);
+	}
+
 	/**
 	 * Abort a running agent: fire AbortController and transition to stopped.
 	 * Returns false if the agent is not running.
@@ -488,6 +547,7 @@ export class Subagent {
 
 	/** Reset for resume: running status, new startedAt, clear completedAt/result/error/listeners. */
 	resetForResume(startedAt: number): void {
+		this.abortController = new AbortController();
 		this.state.resetForResume(startedAt);
 		this.listeners.release();
 	}
@@ -496,16 +556,19 @@ export class Subagent {
 	completeRun(result: TurnLoopResult): void {
 		this.listeners.release();
 
-		const finalStatus: SubagentStatus = result.aborted
-			? "aborted"
-			: result.steered
-				? "steered"
-				: "completed";
+		const finalStatus: SubagentStatus = result.failure
+			? "error"
+			: result.aborted
+				? "aborted"
+				: result.steered
+					? "steered"
+					: "completed";
 		const finalResult =
 			result.responseText +
 			this.workspaceBracket.dispose({ status: finalStatus, description: this.description });
 
-		if (result.aborted) this.markAborted(finalResult);
+		if (result.failure) this.markFailed(result.failure, finalResult);
+		else if (result.aborted) this.markAborted(finalResult);
 		else if (result.steered) this.markSteered(finalResult);
 		else this.markCompleted(finalResult);
 
@@ -517,6 +580,16 @@ export class Subagent {
 		this.subagentSession?.dispose();
 	}
 
+	/** Release heavy session state while preserving the transcript pointer and record. */
+	releaseSession(): void {
+		const session = this.subagentSession;
+		if (!session) return;
+		this.releasedOutputFile = session.outputFile;
+		session.dispose();
+		this.subagentSession = undefined;
+		this._sessionReleased = true;
+	}
+
 	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
 	failRun(err: unknown): void {
 		this.markError(err);
@@ -529,3 +602,18 @@ export class Subagent {
 		this.execution.observer?.onRunFinished?.(this);
 	}
 }
+
+/** Resolve when either the run settles or the caller's wait is interrupted. */
+async function settleOrAbort(run: Promise<void>, signal: AbortSignal): Promise<void> {
+	await new Promise<void>((resolve) => {
+		let done = false;
+		const finish = (): void => {
+			if (done) return;
+			done = true;
+			signal.removeEventListener("abort", finish);
+			resolve();
+		};
+		signal.addEventListener("abort", finish, { once: true });
+		void run.then(finish, finish);
+	});
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/observation/composite-subagent-observer.ts

@@ -33,6 +33,10 @@ export class CompositeSubagentObserver implements SubagentManagerObserver {
     this.dispatch((o) => o.onSubagentCompleted(record), "onSubagentCompleted");
   }
 
+  onSubagentResumed(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentResumed?.(record), "onSubagentResumed");
+  }
+
   onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
     this.dispatch((o) => o.onSubagentCompacted(record, info), "onSubagentCompacted");
   }