@arhen/pi-core-subagent 1.3.51 → 1.3.53

package/README.md

@@ -282,6 +282,8 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 **Steering a running child:** while a background run is active the leader stays responsive, and you can push a message into a live child's session mid-run with `steer_subagent` — e.g. `steer_subagent({ runId, taskId, message: "Ignore tests/, only audit runtime deps" })`. The message queues as a steer if the child is mid-turn and lands at its next model boundary. Omit `taskId` to steer every still-running task in the run. Combined with `notifyPerTask`, this makes a background run feel like a live team you can redirect, not a fire-and-forget blob.
 
+**Resuming a failed child:** a child that dies mid-work (provider rate limit, timeout, network error) keeps its session JSONL and its worktree branch. `resume_subagent({ runId, taskId, model?: "openai/gpt-5", message? })` reopens that session with full context, re-attaches the branch, and prompts it to recap and continue — no respawn, no lost tokens. `model` swaps provider when the original one is exhausted. Refused for tasks that never started (no session file); those you respawn. Wait for the run to settle before resuming (the tool tells you if it hasn't).
+
 ## Tools
 
 | Tool | Purpose |
@@ -292,6 +294,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |
 | `reply_subagent` | answer a child's `ask_parent` question |
 | `steer_subagent` | inject a steering message into a running child's session (queues as steer if mid-turn; lands at its next model boundary) |
+| `resume_subagent` | revive a failed/aborted task in its original session (context + branch preserved); optional `model` swap and custom `message` |
 | `subagent_cancel` | abort a running/queued run |
 
 ### Per-task fields

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.51",
+	"version": "1.3.53",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/format.ts

@@ -228,7 +228,9 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 		`Goal: ${goal}${src}${swap}${tools}`,
 		isStartupFailure(task, kind)
 			? "Never started — stop and diagnose before spawning anything else: a config-level error (model, plan, auth, agent file) fails identically on every respawn."
-			: `Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
+			: kind === "completed"
+				? `Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`
+				: `Session file kept — resume_subagent(runId: "${run.id}", taskId: "${task.id}", model?: ...) revives it with full context. subagent_result for what it produced so far.`,
 	].join("\n");
 }
 export function makeNotice(run: RunSnapshot, kind: string): string {

package/src/index.ts

@@ -8,6 +8,7 @@ import {
 	AwaitParam,
 	ReplyParam,
 	ResultParam,
+	ResumeParam,
 	RunIdParam,
 	SteerParam,
 	SubagentParams,
@@ -140,6 +141,7 @@ export default function (pi: ExtensionAPI) {
 			"Right after spawning, call subagent_status(runId) ONCE before any other work — a child that died on spawn (or never started) is invisible until far later otherwise. If it shows a task failed/never started, fix or respawn immediately.",
 			"Never block with nothing to do: if you have no work left after spawning, end your turn — completion notifies you and wakes a fresh turn with the results. await_subagent/autoAwait while idle only burns time and tokens.",
 			"autoAwait:true only when this SAME turn must consume the result immediately. await_subagent is for syncing with your own parallel work — not the default follow-up to a spawn.",
+			"A task that failed mid-work (provider error, rate limit, timeout) keeps its session file and branch: resume_subagent(runId, taskId, model?) revives it with full context — prefer that over respawning. Respawn only when it never started (no session file).",
 		],
 		parameters: SubagentParams,
 		executionMode: "parallel",
@@ -182,7 +184,7 @@ export default function (pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status("${details.run.id}") now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / subagent_cancel.`,
+						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status("${details.run.id}") now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / resume_subagent / subagent_cancel.`,
 					},
 				],
 				details,
@@ -373,6 +375,34 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool<typeof ResumeParam, { run?: RunSnapshot }>({
+		name: "resume_subagent",
+		label: "Resume Subagent",
+		description:
+			"Revive a failed/aborted task in its original session (full context + worktree branch preserved). Optional `model` swaps provider (e.g. after a rate limit); optional `message` replaces the default 'recap and continue' prompt. Refuses tasks that never started — respawn those.",
+		parameters: ResumeParam,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const { runId, taskId, message, model } = params as {
+				runId: string;
+				taskId: string;
+				message?: string;
+				model?: string;
+			};
+			const res = manager.resumeTask(runId, taskId, ctx, { message, model });
+			if (!res.ok) return { content: [{ type: "text", text: res.reason }], isError: true, details: {} };
+			const run = manager.getRun(runId);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Resumed ${runId}/${taskId} (${res.task.agent})${model ? ` on ${model}` : ""} from ${res.task.sessionFile}${res.task.branch ? `, branch ${res.task.branch}` : ""}.\nNext: subagent_status("${runId}") to confirm it is running; completion will notify you.`,
+					},
+				],
+				details: { run: run ? cloneRun(run) : undefined },
+			};
+		},
+	});
+
 	pi.registerTool<typeof RunIdParam, { aborted?: number }>({
 		name: "subagent_cancel",
 		label: "Subagent Cancel",

package/src/manager.ts

@@ -44,6 +44,7 @@ import {
 	type UsageStats,
 } from "./types.ts";
 import {
+	attachWorktree,
 	branchDiff,
 	claimWorktree,
 	cleanupMerged,
@@ -226,6 +227,12 @@ export function validateThinking(model: Model<Api> | undefined, level: string |
 	}
 }
 
+interface ResumeInput {
+	sessionFile: string;
+	branch?: string;
+	message: string;
+}
+
 interface ChildEventState {
 	pendingFailure?: ReturnType<typeof classifyFailure>;
 	failChildEnd?: (error: Error) => void;
@@ -434,7 +441,11 @@ export class SubagentManager {
 	}
 
 	private notifyTask(run: RunSnapshot, task: TaskSnapshot, kind: "completed" | "failed" | "aborted"): void {
-		const body = makeTaskNotice(run, task, kind);
+		// ponytail: child already pushed its summary via notify_parent — pointer only, no second copy. Upgrade: drop notice entirely if the pointer noise also proves useless.
+		const body =
+			kind === "completed" && task.notifiedParent
+				? `Task ${task.agent} (${task.id}) completed in run ${run.id} — summary already reported. Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`
+				: makeTaskNotice(run, task, kind);
 
 		if (this.collectParked(run.id, { kind: "done", taskId: task.id, agent: task.agent, text: body })) {
 			this.emit("subagent:notification", { runId: run.id, taskId: task.id, kind, body });
@@ -452,6 +463,8 @@ export class SubagentManager {
 		extra?: { taskId?: string; question?: string },
 	): void {
 		if (kind !== "asked" && run.awaited) return;
+		// single-task completed run: the task notice already said everything (failure paths may not have notified per-task)
+		if (kind === "completed" && run.tasks.length === 1 && run.notifyPerTask) return;
 		const body =
 			kind === "asked"
 				? `A subagent is asking you a question (task ${extra?.taskId}): ${extra?.question ?? ""}\nReply with reply_subagent(runId: "${run.id}", taskId: "${extra?.taskId}", message: ...).`
@@ -576,6 +589,7 @@ export class SubagentManager {
 			},
 			onNotifyParent: (_taskId, message, level) => {
 				this.emit("subagent:intercom", { runId: run.id, taskId: task.id, kind: "notify", level, message });
+				task.notifiedParent = true;
 
 				if (this.collectParked(run.id, { kind: "notify", taskId: task.id, agent: task.agent, text: message })) return;
 				try {
@@ -702,6 +716,7 @@ export class SubagentManager {
 		ctx: ExtensionContext,
 		signal: AbortSignal | undefined,
 		onUpdate?: (partial: any) => void,
+		resume?: ResumeInput,
 	): Promise<void> {
 		if (TERMINAL.includes(task.status)) return;
 
@@ -750,7 +765,14 @@ export class SubagentManager {
 
 		let wt: Worktree | undefined;
 		let isolationReason: string | undefined;
-		if (canWrite) {
+		if (canWrite && resume?.branch) {
+			try {
+				wt = attachWorktree(task.cwd, resume.branch);
+				if (!wt) isolationReason = `branch ${resume.branch} no longer exists`;
+			} catch (err) {
+				isolationReason = `git worktree add failed: ${err instanceof Error ? err.message : String(err)}`;
+			}
+		} else if (canWrite) {
 			try {
 				const upstream = (task.needs ?? [])
 					.map((id) => run.tasks.find((t) => t.id === id))
@@ -843,7 +865,9 @@ export class SubagentManager {
 				agentDir: getAgentDir(),
 				modelRuntime: await createChildModelRuntime(ctx),
 				resourceLoader: loader,
-				sessionManager: SessionManager.create(childCwd, undefined, { parentSession: getParentSessionFile(ctx) }),
+				sessionManager: resume
+					? SessionManager.open(resume.sessionFile, undefined, childCwd)
+					: SessionManager.create(childCwd, undefined, { parentSession: getParentSessionFile(ctx) }),
 				model,
 				thinkingLevel: thinking as ThinkingLevel | undefined,
 				tools,
@@ -899,7 +923,7 @@ export class SubagentManager {
 			});
 
 			const maxRuntimeMs = input.maxRuntimeMs ?? (this.autoLimit ? DEFAULT_RUNTIME_MS : UNLIMITED_RUNTIME_MS);
-			const promptPromise = child.prompt(task.task, { source: "extension" });
+			const promptPromise = child.prompt(resume?.message ?? task.task, { source: "extension" });
 			const races: Promise<unknown>[] = [promptPromise, childFailurePromise, childEndPromise];
 			if (maxRuntimeMs > 0) {
 				races.push(
@@ -1297,6 +1321,107 @@ export class SubagentManager {
 		return { run: cloneRun(run) };
 	}
 
+	resumeTask(
+		runId: string,
+		taskId: string,
+		ctx: ExtensionContext,
+		opts: { message?: string; model?: string } = {},
+	): { ok: true; task: TaskSnapshot } | { ok: false; reason: string } {
+		const run = this.runs.get(runId);
+		const task = run?.tasks.find((t) => t.id === taskId);
+		if (!run || !task) return { ok: false, reason: `Unknown ${runId}/${taskId}.` };
+		if (!TERMINAL.includes(task.status))
+			return { ok: false, reason: `${taskId} is still ${task.status} — use steer_subagent.` };
+		if (task.status === "completed") return { ok: false, reason: `${taskId} completed — spawn a new task instead.` };
+		if (!task.sessionFile || !existsSync(task.sessionFile)) {
+			return { ok: false, reason: `${taskId} has no session file to resume (never started) — respawn it.` };
+		}
+		if (this.liveChildren.has(`${runId}:${taskId}`)) return { ok: false, reason: `${taskId} is already live.` };
+		// ponytail: resume only into a settled run — executeTasks' final sweep would abort a task revived mid-run. Upgrade: make the sweep skip tasks with a live child.
+		if (!TERMINAL.includes(run.status)) {
+			return { ok: false, reason: `Run ${runId} is still ${run.status} — wait for it to settle before resuming.` };
+		}
+
+		const tools = task.tools?.filter((t) => !(CHILD_TALK_TOOLS as readonly string[]).includes(t));
+		const write = tools?.some((t) => WRITE_CAPABLE.includes(t)) ?? false;
+		const input: TaskInput = {
+			id: task.id,
+			agent: task.agent,
+			task: task.task,
+			cwd: task.cwd,
+			write,
+			tools: tools?.length ? tools : undefined,
+			model: opts.model ?? task.model,
+			thinking: task.thinking as TaskInput["thinking"],
+			needs: task.needs,
+		};
+		const resume: ResumeInput = {
+			sessionFile: task.sessionFile,
+			branch: task.branch,
+			message:
+				opts.message?.trim() ||
+				`Your previous turn ended with an error (${task.error ?? "unknown"}). Resume where you left off: briefly recap what you already did and what remains, then continue and finish the original task.`,
+		};
+
+		this.cleared = false;
+		this.turnActivity = true;
+		Object.assign(task, {
+			status: "queued" as TaskStatus,
+			error: undefined,
+			endedAt: undefined,
+			finalText: undefined,
+			notifiedParent: false,
+			diffStat: undefined,
+			changedFiles: undefined,
+			worktreeError: undefined,
+		});
+		run.status = "running";
+		run.endedAt = undefined;
+		run.awaited = false;
+		this.settlers.set(run.id, true);
+		this.runControllers.set(run.id, new AbortController());
+		for (const t of run.tasks) this.mailboxes.open(`${run.id}:${t.id}`);
+		this.updateRun(run, ctx);
+		this.emit("subagent:task-resumed", { runId: run.id, taskId: task.id });
+
+		void this.runChild(run, task, input, task.task, ctx, undefined, undefined, resume)
+			.catch((err) => {
+				if (!TERMINAL.includes(task.status)) {
+					this.updateTask(
+						run,
+						task,
+						{ status: "failed", error: err instanceof Error ? err.message : String(err), endedAt: Date.now() },
+						ctx,
+					);
+				}
+			})
+			.then(() => {
+				if (run.notifyPerTask) this.notifyTask(run, task, task.status as "completed" | "failed" | "aborted");
+				this.finishRunIfSettled(run, ctx);
+			});
+		return { ok: true, task };
+	}
+
+	private finishRunIfSettled(run: RunSnapshot, ctx: ExtensionContext): void {
+		if (run.tasks.some((t) => !TERMINAL.includes(t.status))) return;
+		const failed = run.tasks.some((t) => t.status === "failed");
+		const aborted = run.tasks.some((t) => t.status === "aborted");
+		run.status = aborted ? "aborted" : failed ? "failed" : "completed";
+		run.endedAt = Date.now();
+		this.flushWidget(run, ctx);
+		this.emit("subagent:run-completed", {
+			runId: run.id,
+			status: run.status,
+			run: cloneRun(run),
+			aggregateUsage: run.aggregateUsage,
+		});
+		this.settleRun(run.id, run);
+		this.runControllers.delete(run.id);
+		for (const task of run.tasks) this.mailboxes.close(`${run.id}:${task.id}`);
+		this.persist(ctx);
+		this.notifyParent(run, run.status === "completed" ? "completed" : run.status === "aborted" ? "aborted" : "failed");
+	}
+
 	steerTask(runId: string, taskId: string | undefined, message: string): boolean {
 		const run = this.runs.get(runId);
 		if (!run) return false;

package/src/schemas.ts

@@ -77,6 +77,19 @@ export const ReplyParam = Type.Object({
 	taskId: Type.String(),
 	message: Type.String({ description: "Answer for the child" }),
 });
+export const ResumeParam = Type.Object({
+	runId: Type.String(),
+	taskId: Type.String({ description: "Failed/aborted task to revive" }),
+	message: Type.Optional(
+		Type.String({ description: "Prompt delivered on resume (default: recap state, then continue the original task)" }),
+	),
+	model: Type.Optional(
+		Type.String({
+			description:
+				"Model override for the resumed session (provider/model-id) — use when the original provider is rate-limited",
+		}),
+	),
+});
 export const SteerParam = Type.Object({
 	runId: Type.String(),
 	taskId: Type.Optional(Type.String({ description: "Specific task id; defaults to all still-running tasks" })),

package/src/types.ts

@@ -30,6 +30,7 @@ export interface TaskSnapshot {
 	toolCalls: number;
 	lastActivity?: string;
 	finalText?: string;
+	notifiedParent?: boolean;
 	error?: string;
 	model?: string;
 	modelNote?: string;

package/src/worktree.ts

@@ -98,6 +98,33 @@ export function createWorktree(cwd: string, runId: string, taskId: string, baseR
 	return { root, path, branch, base };
 }
 
+export function attachWorktree(cwd: string, branch: string): Worktree | undefined {
+	if (!branch.startsWith(BRANCH_PREFIX)) return undefined;
+	const root = repoRoot(cwd);
+	if (!root) return undefined;
+	const container = subagentsDir(root);
+	if (!container) return undefined;
+	if (!gitOk(root, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`])) return undefined;
+	const path = join(container, branch.slice(BRANCH_PREFIX.length));
+	if (!worktreePaths(root)?.some((p) => samePath(p, path))) {
+		if (existsSync(path)) rmSync(path, { recursive: true, force: true });
+		git(root, ["worktree", "add", path, branch]);
+	}
+	let base: string;
+	try {
+		base = git(root, ["merge-base", "HEAD", branch]);
+	} catch {
+		base = git(root, ["rev-parse", "HEAD"]);
+	}
+	const nm = join(root, "node_modules");
+	if (existsSync(nm) && !existsSync(join(path, "node_modules"))) {
+		try {
+			symlinkSync(nm, join(path, "node_modules"));
+		} catch {}
+	}
+	return { root, path, branch, base };
+}
+
 export function commitWorktree(wt: Worktree, message: string): "committed" | "empty" {
 	return commitIn(wt.path, message, wt.branch);
 }