@ferris1225/pi-subagents 4.2.13 → 4.3.1

package/src/thread-lifecycle.ts

@@ -11,7 +11,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { realpath } from "node:fs/promises";
-import { join, resolve, dirname } from "node:path";
+import { join, resolve } from "node:path";
 import {
 	discoverAgents,
 	isWriteCapableAgent,
@@ -20,14 +20,13 @@ import {
 } from "./agents.ts";
 import { type CompletionMessageItem } from "./completion.ts";
 import {
-	DEFAULT_THINKING_LEVEL,
 	loadConfig,
+	roleThinkingLevel,
 	type SubagentsConfig,
 	type ThinkingLevel,
 } from "./config.ts";
 import {
 	isCurrentBoot,
-	migrateLegacyThreadsManifest,
 	readThreadRecords,
 	referencedDurablePaths,
 	removeThreadRecord,
@@ -35,7 +34,7 @@ import {
 	pruneThreadRecords,
 	restoredResultFromSummary,
 	threadRecordFromThread,
-	ThreadRecord,
+	type ThreadRecord,
 	upsertThreadRecord,
 } from "./durable.ts";
 import {
@@ -54,13 +53,15 @@ import {
 	resolveThinkingLevel,
 } from "./models.ts";
 import { monitor } from "./monitor.ts";
+import { findDuplicateActiveDispatch } from "./prompt.ts";
 import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
+import { emptyUsage } from "./rpc-run.ts";
 import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
 import { forkRetainedSession } from "./session-fork.ts";
 import {
 	buildResumePrompt,
 	getProjectRoot,
-	PROJECT_ROOTS_DIR_NAME,
+	getSubagentsRoot,
 	RpcRunControl,
 	isFailedResult,
 	isModelLevelFailure,
@@ -265,17 +266,16 @@ export interface ResumeReservation {
 }
 
 /** The dispatcher's full internal entry point; the public tool surface only
- * uses the first four parameters plus the per-call `thinking` request. */
+ * uses the first four parameters. */
 export interface StartBackgroundOptions {
-	/** Reasoning strength this dispatch asked for; the user's manual
-	 * `/subagents-setup` choice still outranks it (see resolveDispatchModelRoute). */
-	thinking?: ThinkingLevel;
 	/** Resume path only: the thread whose retained context continues. */
 	existingThread?: SubagentThread;
 	appendedObjectiveOnResume?: boolean;
 	environment?: DispatchEnvironment;
 	seed?: SessionSeed;
 	resumeReservation?: ResumeReservation;
+	/** Chosen by the tool call before the queue can start a fast child. */
+	deliveryRoute?: "background" | "await";
 }
 
 export type StartBackgroundInternal = (
@@ -307,7 +307,6 @@ export function resolveDispatchModelRoute(
 	agent: AgentConfig,
 	config: SubagentsConfig,
 	ctx: ExtensionContext,
-	requestedThinking?: ThinkingLevel,
 ): DispatchModelRoute {
 	const availableModels = availableModelsInScope(ctx);
 	const mainRef = currentModelRef(ctx);
@@ -316,11 +315,10 @@ export function resolveDispatchModelRoute(
 		mainRef,
 		availableRefs: availableModels.map(modelRef),
 	});
-	// agentThinkingLevels only holds a level the user picked by hand in
-	// /subagents-setup (missing = Auto), so that deliberate setting outranks the
-	// dispatching model's per-call guess, which in turn outranks frontmatter.
+	// A `/subagents-setup` override wins; otherwise the role default. No
+	// per-call or frontmatter thinking.
 	const preferred =
-		config.agentThinkingLevels[agent.name] ?? requestedThinking ?? agent.thinking ?? DEFAULT_THINKING_LEVEL;
+		config.agentThinkingLevels[agent.name] ?? roleThinkingLevel(agent.name);
 	const thinkingLevelForModel = (ref?: string): ThinkingLevel => {
 		const model = ref === mainRef && ctx.model
 			? ctx.model
@@ -372,12 +370,12 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		startOptions: StartBackgroundOptions = {},
 	): Promise<SingleResult> => {
 		const {
-			thinking,
 			existingThread,
 			appendedObjectiveOnResume = false,
 			environment,
 			seed,
 			resumeReservation,
+			deliveryRoute = "background",
 		} = startOptions;
 		if (!runtime.sessionActive) {
 			return failedStartResult(agentName, task, "Parent session shut down before this subagent generation could start.");
@@ -396,43 +394,40 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		const agent = resolveLiveAgentTools(discoveredAgent);
 		if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
 			return {
-				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as executor.`),
+				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as artisan.`),
 				isolation,
 			};
 		}
 
 		const originalCwd = resolve(cwd ?? runCtx.cwd);
+		if (!existingThread) {
+			const duplicate = findDuplicateActiveDispatch(runtime.threads.values(), task, originalCwd);
+			if (duplicate) {
+				return failedStartResult(
+					agentName,
+					task,
+					`Duplicate active dispatch matches run #${duplicate.id} (${duplicate.agentName}). Use that logical thread instead; resume #${duplicate.id} when it is eligible.`,
+				);
+			}
+		}
 		const projectRoot = getProjectRoot(runtime.configPath, originalCwd);
 		const sessionsRoot = join(projectRoot, "sessions");
 		const worktreesRoot = join(projectRoot, "worktrees");
 		const scratchRoot = join(projectRoot, "tmp");
 		const previousWorktree = existingThread?.worktree;
 		let worktree = seed?.worktree ?? previousWorktree;
-		if (isolation === "worktree") {
-			if (worktree && worktree.state !== "active") {
-				return {
-					...failedStartResult(agentName, task, `Run #${existingThread?.id ?? "?"} has no active continuation worktree.`),
-					isolation,
-					integrationStatus: worktree.state === "finalizing" ? "pending" : worktree.state,
-				};
-			}
-			if (!worktree) {
-				try {
-					worktree = await createWorktreeIsolation(originalCwd, { tempBaseDir: worktreesRoot });
-				} catch (error) {
-					return {
-						...failedStartResult(agentName, task, error instanceof Error ? error.message : String(error)),
-						isolation,
-					};
-				}
-			}
+		if (isolation === "worktree" && worktree && worktree.state !== "active") {
+			return {
+				...failedStartResult(agentName, task, `Run #${existingThread?.id ?? "?"} has no active continuation worktree.`),
+				isolation,
+				integrationStatus: worktree.state === "finalizing" ? "pending" : worktree.state,
+			};
 		}
-		const executionCwd = worktree?.cwd ?? originalCwd;
-		const worktreeGroup = worktree ? worktreeGroupId(worktree) : undefined;
+		let executionCwd = worktree?.cwd ?? originalCwd;
+		let worktreeGroup = worktree ? worktreeGroupId(worktree) : undefined;
 		// A resume re-runs at the strength its dispatch asked for, so the retained
 		// request survives generations (and, via the durable record, restarts).
-		const requestedThinking = thinking ?? existingThread?.requestedThinkingLevel;
-		const resolvedRoute = resolveDispatchModelRoute(agent, runConfig, runCtx, requestedThinking);
+		const resolvedRoute = resolveDispatchModelRoute(agent, runConfig, runCtx);
 		// Isolation is a persistent system-level invariant, not a one-shot task
 		// prefix: resumes and main-model
 		// handoffs all keep the same worktree boundary.
@@ -447,6 +442,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			isolation,
 			...(worktreeGroup ? { worktreeId: worktreeGroup } : {}),
 		});
+		runtime.claimRunDelivery(runId, deliveryRoute);
 		const generation = (existingThread?.generation ?? 0) + 1;
 		const pending: SingleResult = {
 			...queuedResult(route.agent, task, thinkingLevel),
@@ -493,7 +489,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			thread.cwd = originalCwd;
 			thread.executionCwd = executionCwd;
 			thread.thinkingLevel = thinkingLevel;
-			thread.requestedThinkingLevel = requestedThinking;
 			thread.isolation = isolation;
 			thread.worktree = worktree;
 			thread.state = "queued";
@@ -517,7 +512,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				cwd: originalCwd,
 				executionCwd,
 				thinkingLevel,
-				requestedThinkingLevel: requestedThinking,
 				isolation,
 				worktree,
 				state: "queued",
@@ -532,11 +526,12 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			};
 			runtime.threads.set(runId, thread);
 		}
-		installThreadLifecycle(thread, {
+		const installCurrentLifecycle = (): void => installThreadLifecycle(thread, {
 			runtime,
 			runCtx,
 			startBackground: (...args) => startBackground(...args),
 		});
+		if (isolation === "shared" || worktree) installCurrentLifecycle();
 
 		const onLive = makeLiveHandler(runId, generation);
 		// Shared write-capable runs serialize on the repository lane so their
@@ -545,6 +540,20 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		const reserveManagedLane = isolation === "shared" && isWriteCapableAgent(agent);
 		const runGeneration = async (backgroundSignal: AbortSignal, controller: AbortController): Promise<void> => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
+				if (isolation === "worktree" && !worktree) {
+					const prepared = await createWorktreeIsolation(originalCwd, { tempBaseDir: worktreesRoot });
+					if (runtime.threads.get(runId)?.generation !== generation || backgroundSignal.aborted) {
+						await prepared.discard().catch(() => undefined);
+						return;
+					}
+					worktree = prepared;
+					executionCwd = prepared.cwd;
+					worktreeGroup = worktreeGroupId(prepared);
+					thread.worktree = prepared;
+					thread.executionCwd = executionCwd;
+					monitor.setIsolation(runId, "worktree", "pending", worktreeGroup);
+					installCurrentLifecycle();
+				}
 				// The generation body owns a process slot from here (a lane wait, if
 				// any, was granted above). Recording the transition synchronously keeps
 				// every "queued" surface truthful: only runs still pending in the pool
@@ -557,7 +566,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				let activeIdleTimeoutMs = runConfig.idleTimeoutSec * 1000;
 				try {
 					const startConfig = await loadConfig(runtime.configPath);
-					const resolvedStart = resolveDispatchModelRoute(agent, startConfig, runCtx, requestedThinking);
+					const resolvedStart = resolveDispatchModelRoute(agent, startConfig, runCtx);
 					activeRoute = isolation === "worktree"
 						? { ...resolvedStart, agent: withWorktreeSystemPrompt(resolvedStart.agent) }
 						: resolvedStart;
@@ -658,10 +667,10 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					thread.lifecycleOperation === "settle" &&
 					!thread.retired;
 				try {
-				// For isolated writers the apply runs only after the child settled,
-				// so this lifecycle owner integrates the complete settled state
-				// exactly once under the repository lane.
-				await thread.finalizeIsolation(generation, result);
+					// The child process has exited. Isolated Git finalization remains
+					// lifecycle-owned and awaited, but no longer consumes a process slot.
+					if (isolation === "worktree") runtime.backgroundQueue.suspend(controller);
+					await thread.finalizeIsolation(generation, result);
 				if (!ownsSettlement()) return;
 
 				const failed = isFailedResult(result);
@@ -692,41 +701,33 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					block: modelLevel
 						? `${formatCompletionBlock(result, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, result.projectCwd ?? originalCwd) })}\n\n${modelLevelTakeoverNote(result, { runId })}`
 						: formatCompletionBlock(result, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, result.projectCwd ?? originalCwd) }),
-					triggerTurn: true,
 					usage: result.usage,
 				};
-					if (modelLevel) {
-						const detail = result.errorMessage?.trim() || "model unavailable or broken";
-						runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${detail} — task handed to the main window`, "error");
-					} else if (dispatchFailed) {
-						runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${result.errorMessage ?? "dispatch crashed"}`, "error");
-					}
-					if (failed) {
-						runtime.sendCompletionGroup([completion]);
-						runtime.completionBatcher.flush();
-					} else {
-						runtime.completionBatcher.push(completion);
-					}
+				if (modelLevel) {
+					const detail = result.errorMessage?.trim() || "model unavailable or broken";
+					runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${detail} — task handed to the main window`, "error");
+				} else if (dispatchFailed) {
+					runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${result.errorMessage ?? "dispatch crashed"}`, "error");
+				}
+				runtime.publishRunCompletion(runId, completion, failed);
 				} finally {
 					if (ownsSettlement()) thread.lifecycleOperation = undefined;
 				}
 			};
 		const queuedGeneration = reserveManagedLane
 			? async (backgroundSignal: AbortSignal, controller: AbortController): Promise<void> => {
-					// This task may spend its whole life waiting for the repository
-					// lane (every shared write-capable generation serializes on it).
-					// Holding a process slot while only waiting let a batch of shared
-					// writers park the entire pool and starve independent read-only
-					// dispatches that could have started immediately, so the slot is
-					// released up front; the lane itself still serializes same-repo
-					// writers, and abort/quiesce guarantees are unchanged.
+					// Waiting for repository serialization must not consume a process
+					// slot. Once the lane is granted, reacquire through the same FIFO
+					// scheduler before any child process can spawn.
 					runtime.backgroundQueue.suspend(controller);
-					// A lane wait is write serialization, not slot pacing: the model
-					// must never read it as an exhausted pool.
 					monitor.setWaitReason(runId, "repository-lane");
 					await runInManagedRepositoryLane(
 						originalCwd,
-						() => runGeneration(backgroundSignal, controller),
+						async () => {
+							monitor.setWaitReason(runId, "process-slot");
+							if (!(await runtime.backgroundQueue.acquire(controller))) return;
+							await runGeneration(backgroundSignal, controller);
+						},
 						backgroundSignal,
 					);
 				}
@@ -785,6 +786,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						};
 					thread.lastResult = crashed;
 					runtime.retainSession(crashed);
+					if (isolation === "worktree" && thread.worktree) runtime.backgroundQueue.suspend(thread.queueController);
 					await thread.finalizeIsolation(generation, crashed);
 					if (!ownsSettlement()) return;
 					thread.state = "failed";
@@ -798,15 +800,11 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					if (!runtime.sessionActive || !ownsSettlement()) return;
 					try {
 						runCtx.ui.notify(`✗ ${crashed.agent} dispatch failed: ${crashed.errorMessage}`, "error");
-						runtime.sendCompletionGroup([
-							{
-								agent: crashed.agent,
-								block: formatCompletionBlock(crashed, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, crashed.projectCwd ?? originalCwd) }),
-								triggerTurn: true,
-								usage: crashed.usage,
-							},
-						]);
-						runtime.completionBatcher.flush();
+						runtime.publishRunCompletion(runId, {
+							agent: crashed.agent,
+							block: formatCompletionBlock(crashed, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, crashed.projectCwd ?? originalCwd) }),
+							usage: crashed.usage,
+						}, true);
 					} catch {
 						/* a second delivery failure must not throw through the queue */
 					}
@@ -986,6 +984,9 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 			return failedStartResult(thread.agentName, thread.task, "resume objective must be non-blank when provided.");
 		}
 		if (thread.retired) return failedStartResult(thread.agentName, thread.task, `Run #${runId} was retired by subagent_stop.`);
+		if (thread.resumeUnavailableReason) {
+			return failedStartResult(thread.agentName, thread.task, thread.resumeUnavailableReason);
+		}
 		if (thread.lifecycleOperation) {
 			return failedStartResult(thread.agentName, thread.task, `Run #${runId} is already resuming.`);
 		}
@@ -1182,9 +1183,6 @@ function createRestoredThread(
 		cwd: record.cwd,
 		executionCwd: record.executionCwd,
 		...(record.thinkingLevel ? { thinkingLevel: record.thinkingLevel as ThinkingLevel } : {}),
-		...(record.requestedThinkingLevel
-			? { requestedThinkingLevel: record.requestedThinkingLevel as ThinkingLevel }
-			: {}),
 		isolation: record.isolation,
 		worktree,
 		state,
@@ -1249,16 +1247,53 @@ export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<n
 		const worktree = record.worktree
 			? await restoreWorktreeIsolation(record.worktree).catch(() => undefined)
 			: undefined;
-		// A worktree thread whose isolated filesystem is gone cannot continue its
-		// isolation invariant; surface it as failed instead of pretending.
-		const state: ThreadState = worktree
-			? "parked"
-			: record.isolation === "worktree" && record.worktree
-				? "failed"
-				: "parked";
-		const thread = createRestoredThread(runtime, record, worktree, state);
+		const restorationFailed = record.isolation === "worktree" && record.worktree !== undefined && !worktree;
+		const thread = createRestoredThread(runtime, record, worktree, restorationFailed ? "failed" : "parked");
 		runtime.threads.set(record.runId, thread);
 		runtime.sessionDirs.add(record.sessionDir!);
+		if (restorationFailed) {
+			const reason = `Run #${record.runId}'s recorded worktree could not be restored; isolated edits may be unavailable. The retained session and durable record were kept, but this thread cannot be resumed.`;
+			thread.resumeUnavailableReason = reason;
+			thread.restorationRecord = record;
+			const previous = restoredResultFromSummary(record);
+			const failed: SingleResult = {
+				agent: record.agentName,
+				task: record.task,
+				exitCode: 1,
+				messages: previous?.messages ?? [],
+				stderr: reason,
+				usage: previous?.usage ?? emptyUsage(),
+				model: previous?.model,
+				thinking: previous?.thinking,
+				stopReason: "error",
+				errorMessage: reason,
+				dispatchFailed: true,
+				sessionId: record.sessionId,
+				sessionDir: record.sessionDir,
+				projectCwd: record.cwd,
+				runId: record.runId,
+				isolation: "worktree",
+				integrationStatus: "retained",
+			};
+			thread.lastResult = failed;
+			runtime.registerRunResult(record.runId, failed);
+			monitor.restoreRun({
+				id: record.runId,
+				agent: record.agentName,
+				task: record.task,
+				status: "failed",
+				elapsedMs: record.elapsedMs,
+				isolation: "worktree",
+				integrationStatus: "retained",
+			});
+			runtime.claimRunDelivery(record.runId, "background");
+			runtime.publishRunCompletion(record.runId, {
+				agent: record.agentName,
+				block: `### Subagent restoration failed: #${record.runId} ${record.agentName}\n\n${reason}`,
+				usage: failed.usage,
+			}, true);
+			continue;
+		}
 		monitor.restoreRun({
 			id: record.runId,
 			agent: record.agentName,
@@ -1280,9 +1315,9 @@ export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<n
 	return restoredIds;
 }
 
-/** Load-time durable bootstrap: restore threads, age out expired records, and
+/** Session-start durable bootstrap: restore threads, age out expired records, and
  * sweep leaked temp/state directories. Every stage is best-effort so a broken
- * manifest never blocks extension registration.
+ * manifest never blocks the session.
  *
  * Restore is published on the runtime as `durableRestore` before this returns,
  * so callers that must see restored threads await that pass alone and never the
@@ -1291,9 +1326,6 @@ export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<n
 export function bootstrapDurableState(runtime: SubagentRuntime): Promise<void> {
 	const restore = (async () => {
 		try {
-			// Records from a pre-per-project manifest must land in their project
-			// roots before restore reads anything.
-			await migrateLegacyThreadsManifest(runtime.configPath);
 			runtime.restoredRunIds = await restoreDurableThreads(runtime);
 		} catch {
 			/* restore is best-effort */
@@ -1307,7 +1339,7 @@ export function bootstrapDurableState(runtime: SubagentRuntime): Promise<void> {
 		} catch {
 			/* retention is best-effort */
 		}
-		const projectRoots = join(dirname(runtime.configPath), PROJECT_ROOTS_DIR_NAME);
+		const projectRoots = getSubagentsRoot(runtime.configPath);
 		try {
 			sweepProjectTempDirs(projectRoots);
 		} catch {

package/src/tools.ts

@@ -46,14 +46,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 	pi.registerTool({
 		name: "subagent_control",
 		label: "Subagent Control",
-		description: [
-			"Resume an existing sub-agent thread by stable run id: a parked, completed, or failed retained thread restarts with the same run id and cumulative active time.",
-			"Omit objective to continue the current goal, or provide one to append it to retained context and make it the displayed goal. Threads parked or interrupted by a shutdown/reload are restorable; use subagent_stop for destructive cancellation.",
-		].join(" "),
-		promptSnippet: "Resume a parked or settled subagent thread with its retained context.",
-		promptGuidelines: [
-			"Resume keeps the run id and retained context; use subagent_stop only for destructive cancellation, which retires that thread's session.",
-		],
+		description: "Resume a parked or settled child thread by run id, reusing its retained session when available. An optional objective is appended to its current goal.",
 		parameters: SubagentControlParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -91,10 +84,8 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 						const mode = objective
 							? `appended objective: ${currentObjective}`
 							: `continuing current objective: ${currentObjective}`;
-						const context = hadRetainedSession
-							? "the same retained session and prior context are preserved"
-							: "no prior child session existed, so only the logical run and objective are continued";
-						return { content: [{ type: "text", text: `Resumed run #${thread.id}, ${mode}; ${context}, and cumulative active time is preserved. It runs in the background — keep working; the result resumes you automatically.` }], details: {} };
+						const context = hadRetainedSession ? "retained context reused" : "no prior child context";
+						return { content: [{ type: "text", text: `Resumed run #${thread.id}: ${mode}; ${context}.` }], details: {} };
 					}
 				}
 			} catch (error) {
@@ -125,14 +116,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 	pi.registerTool({
 		name: "subagent_stop",
 		label: "Subagent Stop",
-		description: [
-			"Destructively stop a sub-agent thread: terminate active work, deliver its aborted partial result, and retire any retained session so it cannot be resumed.",
-			"Pass id (run id or prefix) to stop one active, parked, or completed thread; all: true stops every active run.",
-		].join(" "),
-		promptSnippet: "Stop a running background subagent (id from dispatch output; or all: true).",
-		promptGuidelines: [
-			"Stop a run when its task is obsolete, stuck, or superseded — do not leave it burning tokens. It then reports as failed with 'aborted' plus its partial output.",
-		],
+		description: "Stop and retire one child thread by run id/prefix, or every active thread with all: true.",
 		parameters: SubagentStopParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/agents/executor.md

@@ -1,54 +0,0 @@
----
-name: executor
-description: A self-contained unit that changes the repository or condenses inputs — implement, fix, refactor, test, clean up, sync docs, merge fan-out results — carried through verification to a result-only handoff.
-thinking: high
-# No `tools` field => inherits all tools (full capability).
----
-
-You are an executor agent with full capabilities in an isolated context window. You own one delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
-
-Repository instructions (AGENTS.md) and any skills available in this session apply to you as to any agent: follow their process for the domains they own (language style, tests, debugging, cleanup discipline, verification). Where a skill covers the same ground as this brief, the skill's discipline wins — except for the release boundary below, which always wins.
-
-## Procedure
-
-1. **Context.** Read the brief fully, plus referenced files and images, before acting. If critical context is missing, state what is missing rather than guessing.
-2. **Plan.** Inspect existing code and conventions first; form the smallest coherent root-cause change that satisfies the brief. Prefer the design that deletes complexity over one that rearranges it. No unrelated refactors or standalone docs work unless the brief asks.
-3. **Confirm.** A finding is not a change. Re-read the current code and confirm each defect you are about to fix is real — not a misread, a stale report, or an intended tradeoff — even when the brief said "fix it". A false positive means zero edits and a note.
-4. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize README/docs/comments your change directly affects; never defer that drift.
-5. **Verify.** Run the project's format/build/tests when they exist. NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
-
-## Conditional playbooks
-
-Skip both unless the brief matches one.
-
-**Cleanup** (dead code, duplication, simplification): a candidate is not a deletion. Re-read the load-bearing files and repeat the decisive searches yourself — never inherit proof from another agent's report — and search the whole repository for consumers first. Keep a candidate when a real consumer exists, dynamic reachability is unresolved, or the cut removes a user capability, public API, persisted format, or compatibility path the brief did not explicitly approve. Finding no safe cut and making zero edits is valid.
-
-**Merging inputs** (result artifacts, reports, logs): read every named input fully before writing, deduplicate restatements into one attributed entry, and report surviving conflicts side by side instead of averaging them away. Stay within the named inputs; report what they cannot answer as a gap.
-
-## Boundaries
-
-- Never commit, push, publish, tag, release, or bump a package version — the caller owns every release action, even when repository instructions normally automate release after green checks.
-- Children are leaf processes: you cannot dispatch sub-agents.
-- Never change runtime behavior to make documentation true; report the defect instead.
-
-## Output format
-
-Return only the concrete outcome. Do not repeat the task brief, the plan, the root-cause investigation, or the tool chronology.
-
-## Completed
-
-What was done, in a few lines.
-
-## Files Changed
-
-- `path/to/file.ts` — what changed.
-
-## Verification
-
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean). State explicitly anything you could not run and why.
-
-## Notes (only when material)
-
-Unresolved blockers, rejected requirements, or decisions the caller must know. Omit when nothing actionable.
-
-Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.

package/agents/explorer.md

@@ -1,37 +0,0 @@
----
-name: explorer
-description: Fast read-only reconnaissance for broad or multi-file search in unfamiliar areas; returns exact paths and compressed findings as retrieval leads.
-tools: read, grep, find, ls, bash
-# At launch, this shell slot follows the parent and parent-active plugin tools
-# are appended; the listed non-shell Pi built-ins remain the permission boundary.
-thinking: low
----
-
-You are an explorer agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings so another agent does not repeat the whole search. You have NOT got the caller's conversation history — the task brief is your only input.
-
-## Hard constraints
-
-- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands. Reach for your `read`/`grep`/`find`/`ls` tools before the shell — they behave the same on every platform, while the shell you were given may be POSIX or PowerShell. Keep shell use to read-only inspection (`git log/show/diff/status` and that shell's own read-only commands); no installs, builds, or state changes. Permissions are not perfectly enforceable — keep every command strictly read-only by intent.
-- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read the cited line ranges before acting on your results.
-
-## Workflow
-
-1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
-2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
-3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
-4. Record exact paths and line ranges so the caller can jump straight in.
-5. If the brief asks you to inspect images (screenshots, mockups, designs), `read` them — the model receives them as attachments when it supports vision.
-
-Thoroughness scales with the task (default medium): quick = targeted lookups in key files; medium = follow imports and callers, read critical sections; thorough = trace dependencies across modules, check tests and types.
-
-## Final response
-
-Return only retrieval results, one bare bullet per finding — a single line: path, the fact, nothing else:
-
-```text
-- `path/to/file.ts:10-50` — the fact
-Start here: `path/to/file.ts` — entry symbol and why (only when the caller could not guess it)
-Gaps: unresolved uncertainty (only when real)
-```
-
-No preamble or closing summary. Do not repeat the task brief, inventory every file opened, paste nonessential code, or narrate the search; every line must carry a path with a fact or name a gap — delete anything else. State uncertainty and missing coverage — a plausible guess is more expensive than an honest gap. Stay under 15 lines by default; go longer only when the brief genuinely demands a wide survey — the 40-line delivery cap truncates your tail (usually the Gaps) and the caller pays for every line.