@ferris1225/pi-subagents 4.3.4 → 4.3.6

package/src/lifecycle/thread-restore.ts

@@ -0,0 +1,253 @@
+/** Durable restoration and startup hygiene for logical sub-agent threads. */
+
+import { rm } from "node:fs/promises";
+import { type ThinkingLevel } from "../configuration/config.ts";
+import {
+	isCurrentBoot,
+	pruneStaleProjectRoots,
+	pruneThreadRecords,
+	readThreadRecords,
+	referencedDurablePaths,
+	removeThreadRecord,
+	restoredResultFromSummary,
+	type ThreadRecord,
+} from "./durable.ts";
+import { failedStartResult } from "../presentation/format.ts";
+import { monitor } from "../presentation/monitor.ts";
+import { emptyUsage } from "../execution/rpc-control.ts";
+import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
+import {
+	getSubagentsRoot,
+	RpcRunControl,
+	sessionExists,
+	sweepProjectResultArtifacts,
+	type SingleResult,
+} from "../execution/spawn.ts";
+import { isProcessAlive, killProcessTree, sweepProjectDurableDirs, sweepProjectTempDirs } from "../isolation/temp-hygiene.ts";
+import { readRecoveryRecords, referencedRecoveryPaths } from "../isolation/recovery.ts";
+import {
+	isPathInside,
+	restoreWorktreeIsolation,
+	worktreeGroupId,
+	type WorktreeIsolation,
+} from "../isolation/worktree.ts";
+import { installThreadLifecycle } from "./thread-lifecycle.ts";
+
+/** Dropped restored record: no session means no context to resume, so its
+ * artifacts go away with the record. */
+async function discardRestoredRecord(runtime: SubagentRuntime, record: ThreadRecord): Promise<void> {
+	if (record.sessionDir) {
+		await rm(record.sessionDir, { recursive: true, force: true }).catch(() => undefined);
+		runtime.sessionDirs.delete(record.sessionDir);
+	}
+	if (record.worktree && (record.worktree.state === "active" || record.worktree.state === "retained")) {
+		const worktree = await restoreWorktreeIsolation(record.worktree).catch(() => undefined);
+		await worktree?.discard().catch(() => undefined);
+	}
+	await removeThreadRecord(runtime.configPath, record.runId, record.cwd).catch(() => undefined);
+}
+
+function createRestoredThread(
+	runtime: SubagentRuntime,
+	record: ThreadRecord,
+	worktree: WorktreeIsolation | undefined,
+	state: ThreadState,
+): SubagentThread {
+	const thread: SubagentThread = {
+		id: record.runId,
+		generation: record.generation,
+		agentName: record.agentName,
+		task: record.task,
+		cwd: record.cwd,
+		executionCwd: record.executionCwd,
+		...(record.thinkingLevel ? { thinkingLevel: record.thinkingLevel as ThinkingLevel } : {}),
+		isolation: record.isolation,
+		worktree,
+		state,
+		control: new RpcRunControl(record.task, record.generation),
+		generationCompletion: Promise.resolve(),
+		lifecycleVersion: 0,
+		elapsedMs: record.elapsedMs,
+		sessionId: record.sessionId,
+		sessionDir: record.sessionDir,
+		lastResult: restoredResultFromSummary(record),
+		resume: async () => failedStartResult(record.agentName, record.task, "Thread resume was not initialized."),
+		finalizeIsolation: async () => undefined,
+	};
+	installThreadLifecycle(thread, {
+		runtime,
+		startBackground: (...args) => {
+			const dispatcher = runtime.dispatcher;
+			if (!dispatcher) {
+				return Promise.resolve(failedStartResult(
+					record.agentName,
+					record.task,
+					`Run #${record.runId} cannot continue: no dispatch context is available yet. Dispatch any subagent once, then retry.`,
+				));
+			}
+			return dispatcher(...args);
+		},
+	});
+	return thread;
+}
+
+/** Rebuild interrupted (parked) threads from the durable manifest after a
+ * reload or restart. Orphaned children recorded by the previous process are
+ * killed first; records whose retained session vanished — and settled records
+ * left by older versions, which hold no work worth resuming — drop out with
+ * their artifacts. Returns the restored run ids. */
+export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<number[]> {
+	const records = await readThreadRecords(runtime.configPath);
+	const restoredIds: number[] = [];
+	for (const record of records) {
+		if (runtime.threads.has(record.runId) || monitor.findRun(record.runId)) continue;
+		if (record.state !== "parked") {
+			await discardRestoredRecord(runtime, record);
+			continue;
+		}
+		// A child orphaned by reload/crash may still hold the retained session.
+		// The on-disk session checkpoint is what survives; kill the writer — but
+		// only while the recorded pids are still ours. Across a reboot the same
+		// numbers belong to unrelated processes.
+		if (isCurrentBoot(record)) {
+			for (const pid of record.childPids) {
+				if (isProcessAlive(pid)) killProcessTree(pid);
+			}
+		}
+		const sessionValid =
+			record.sessionId !== undefined &&
+			record.sessionDir !== undefined &&
+			sessionExists(record.sessionDir, record.sessionId);
+		if (!sessionValid) {
+			await discardRestoredRecord(runtime, record);
+			continue;
+		}
+		const worktree = record.worktree
+			? await restoreWorktreeIsolation(record.worktree).catch(() => undefined)
+			: undefined;
+		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,
+			task: record.task,
+			status: "parked",
+			elapsedMs: record.elapsedMs,
+			isolation: record.isolation,
+			...(record.worktree
+				? {
+					integrationStatus: record.worktree.state === "active"
+						? ("pending" as const)
+						: record.worktree.state,
+					...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
+				}
+				: {}),
+		});
+		restoredIds.push(record.runId);
+	}
+	return restoredIds;
+}
+
+/** 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 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
+ * hygiene sweeps behind it. Hygiene still runs after restore: pruning decides
+ * what to delete from the records restore has already claimed. */
+export function bootstrapDurableState(runtime: SubagentRuntime): Promise<void> {
+	const restore = (async () => {
+		try {
+			runtime.restoredRunIds = await restoreDurableThreads(runtime);
+		} catch {
+			/* restore is best-effort */
+		}
+	})();
+	runtime.durableRestore = restore;
+	return (async () => {
+		await restore;
+		try {
+			await pruneThreadRecords(runtime.configPath);
+		} catch {
+			/* retention is best-effort */
+		}
+		const projectRoots = getSubagentsRoot(runtime.configPath);
+		try {
+			sweepProjectTempDirs(projectRoots);
+		} catch {
+			/* temp hygiene is best-effort */
+		}
+		try {
+			// Sessions and worktrees outlive their process on purpose, so only
+			// ownership separates state a live pi still resumes from state a crash
+			// abandoned. Valid thread and recovery records always keep their paths.
+			const records = await readThreadRecords(runtime.configPath);
+			const recoveryRecords = await readRecoveryRecords(runtime.configPath);
+			const referenced = [...referencedDurablePaths(records)];
+			referenced.push(...await referencedRecoveryPaths(runtime.configPath, recoveryRecords));
+			sweepProjectDurableDirs(projectRoots, {
+				keep: (path) => referenced.some((claimed) => isPathInside(path, claimed)),
+			});
+		} catch {
+			/* durable-state hygiene is best-effort */
+		}
+		try {
+			// Result excerpts are bounded on write, which never reaches a project
+			// that has stopped producing them.
+			sweepProjectResultArtifacts(projectRoots);
+		} catch {
+			/* result retention is best-effort */
+		}
+		try {
+			await pruneStaleProjectRoots(runtime.configPath);
+		} catch {
+			/* project-root hygiene is best-effort */
+		}
+	})();
+}

package/src/lifecycle/thread-shared.ts

@@ -0,0 +1,269 @@
+/** Shared contracts and coordination primitives for logical sub-agent threads. */
+
+import { realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isWriteCapableAgent, type AgentConfig } from "../delegation/agents.ts";
+import { roleThinkingLevel, type SubagentsConfig, type ThinkingLevel } from "../configuration/config.ts";
+import { removeThreadRecord, threadRecordFromThread, upsertThreadRecord } from "./durable.ts";
+import {
+	availableModelsInScope,
+	currentModelRef,
+	findModelByRef,
+	modelRef,
+	resolveAgentModelRoute,
+	resolveThinkingLevel,
+} from "../configuration/models.ts";
+import type { SubagentRuntime, SubagentThread } from "./runtime.ts";
+import { getProjectRoot, type SingleResult } from "../execution/spawn.ts";
+import { resolveRepositoryRoot, type IsolationMode, type WorktreeIsolation } from "../isolation/worktree.ts";
+
+/** Control operations must never wait forever on a settling generation: the
+ * queue task can legitimately spend minutes in worktree finalization (bounded
+ * per-Git-command timeouts) or wait behind the managed repository lane. After
+ * this deadline the control path owns the lifecycle synchronously and proceeds
+ * while the stuck tail settles silently in the background. */
+export const CONTROL_QUIESCE_TIMEOUT_MS = 20_000;
+
+/** Resolve true when the promise settles, or false after the bounded deadline. */
+export function quiesced(promise: Promise<unknown>, timeoutMs: number = CONTROL_QUIESCE_TIMEOUT_MS): Promise<boolean> {
+	return Promise.race([
+		promise.then(() => true, () => true),
+		new Promise<boolean>((resolve) => {
+			const timer = setTimeout(() => resolve(false), timeoutMs);
+			if (typeof timer.unref === "function") timer.unref();
+		}),
+	]);
+}
+
+const managedRepositoryRootTails = new Map<string, Promise<void>>();
+
+async function canonicalManagedRepositoryRoot(cwd: string): Promise<string> {
+	try {
+		// Repository identity does not depend on HEAD: empty repositories must
+		// serialize root and nested cwd requests under the same lane too.
+		return await resolveRepositoryRoot(cwd);
+	} catch {
+		try {
+			return await realpath(resolve(cwd));
+		} catch {
+			return resolve(cwd);
+		}
+	}
+}
+
+/** Run one operation under the canonical original-repository lane.
+ *
+ * Shared write-capable generations use the abortable overload for their whole
+ * run. Isolated generations use the non-abortable overload only for their
+ * final worktree apply, so model work remains parallel while the original
+ * checkout mutation cannot race a shared writer.
+ */
+export async function runInManagedRepositoryLane<T>(
+	cwd: string,
+	task: () => Promise<T>,
+): Promise<T>;
+export async function runInManagedRepositoryLane<T>(
+	cwd: string,
+	task: () => Promise<T>,
+	signal: AbortSignal,
+): Promise<T | undefined>;
+export async function runInManagedRepositoryLane<T>(
+	cwd: string,
+	task: () => Promise<T>,
+	signal?: AbortSignal,
+): Promise<T | undefined> {
+	if (signal?.aborted) return undefined;
+	const root = await canonicalManagedRepositoryRoot(cwd);
+	const key = process.platform === "win32" ? root.toLowerCase() : root;
+	const previous = managedRepositoryRootTails.get(key) ?? Promise.resolve();
+	let release!: () => void;
+	const gate = new Promise<void>((resolveGate) => {
+		release = resolveGate;
+	});
+	const tail = previous.catch(() => undefined).then(() => gate);
+	managedRepositoryRootTails.set(key, tail);
+	let onAbort: (() => void) | undefined;
+	try {
+		if (signal) {
+			await Promise.race([
+				previous.catch(() => undefined),
+				new Promise<void>((resolveAborted) => {
+					if (signal.aborted) resolveAborted();
+					else {
+						onAbort = resolveAborted;
+						signal.addEventListener("abort", onAbort, { once: true });
+					}
+				}),
+			]);
+		} else {
+			await previous.catch(() => undefined);
+		}
+		if (signal?.aborted) return undefined;
+		return await task();
+	} finally {
+		if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+		release();
+		// An aborted waiter may finish before the prior owner. Keep its chained
+		// tail installed until that owner also settles, otherwise a newcomer could
+		// observe an empty map and race the still-running workflow.
+		void tail.then(() => {
+			if (managedRepositoryRootTails.get(key) === tail) managedRepositoryRootTails.delete(key);
+		});
+	}
+}
+
+/** Track resume setup that has claimed a thread but has not yet enqueued
+ * its next generation. Shutdown invalidates these claims and waits for cleanup. */
+export function beginRuntimePreflight(runtime: SubagentRuntime): () => void {
+	let resolvePreflight!: () => void;
+	const preflight = new Promise<void>((resolve) => {
+		resolvePreflight = resolve;
+	});
+	runtime.preflightOperations.add(preflight);
+	return () => {
+		runtime.preflightOperations.delete(preflight);
+		resolvePreflight();
+	};
+}
+
+/** Synchronous CAS used by lifecycle controls across their async preflight. */
+export function ownsResumeReservation(
+	runtime: SubagentRuntime,
+	thread: SubagentThread,
+	reservation: { version: number; generation: number; sessionId?: string; sessionDir?: string },
+): boolean {
+	return (
+		runtime.sessionActive &&
+		runtime.threads.get(thread.id) === thread &&
+		!thread.retired &&
+		thread.lifecycleOperation === "resume" &&
+		thread.lifecycleVersion === reservation.version &&
+		thread.generation === reservation.generation &&
+		thread.sessionId === reservation.sessionId &&
+		thread.sessionDir === reservation.sessionDir
+	);
+}
+
+/** Fire-and-forget durable checkpoint. Parked threads stay resumable across
+ * reloads; a settled thread drops its record so the manifest only exists
+ * while unfinished work needs it. The live session keeps working when the
+ * manifest is unwritable; only cross-reload resume is degraded. */
+export function persistThreadCheckpoint(
+	runtime: SubagentRuntime,
+	thread: SubagentThread,
+	state: "parked" | "completed" | "failed",
+): void {
+	const write = state === "parked"
+		? upsertThreadRecord(runtime.configPath, threadRecordFromThread(thread, state))
+		: removeThreadRecord(runtime.configPath, thread.id, thread.cwd);
+	void write.catch(() => undefined);
+}
+
+const WORKTREE_ISOLATION_INSTRUCTIONS =
+	"You are running in a temporary detached Git worktree. Work only in the current cwd; do not create another worktree or manually copy/apply changes to the original checkout. The parent dispatcher will integrate your tracked, deleted, and untracked changes when this thread finally settles.";
+
+export function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
+	return {
+		...agent,
+		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\n${WORKTREE_ISOLATION_INSTRUCTIONS}`.trim(),
+	};
+}
+
+/** Only write-capable agents can run in an isolated worktree. */
+export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
+	return isWriteCapableAgent(agent);
+}
+
+export interface DispatchEnvironment {
+	ctx: ExtensionContext;
+	config: SubagentsConfig;
+	agents: AgentConfig[];
+}
+
+export interface SessionSeed {
+	sessionId?: string;
+	sessionDir?: string;
+	prompt?: string;
+	worktree?: WorktreeIsolation;
+}
+
+export interface ResumeReservation {
+	version: number;
+	generation: number;
+	sessionId?: string;
+	sessionDir?: string;
+}
+
+/** The dispatcher's full internal entry point; the public tool surface only
+ * uses the first four parameters. */
+export interface StartBackgroundOptions {
+	/** 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 = (
+	agentName: string,
+	task: string,
+	cwd: string | undefined,
+	isolation?: IsolationMode,
+	options?: StartBackgroundOptions,
+) => Promise<SingleResult>;
+
+export interface ThreadLifecycleDeps {
+	runtime: SubagentRuntime;
+	/** Fallback context when a control caller supplies none; restored threads
+	 * install without one and rely on the per-call context. */
+	runCtx?: ExtensionContext;
+	/** Fresh dispatch passes the live dispatcher; restored threads resolve it
+	 * from the runtime at call time so they never pin a stale closure. */
+	startBackground: StartBackgroundInternal;
+}
+
+interface DispatchModelRoute {
+	agent: AgentConfig;
+	mainFallbackRef?: string;
+	thinkingLevel: ThinkingLevel;
+	thinkingLevelForModel: (ref?: string) => ThinkingLevel;
+}
+
+export function resolveDispatchModelRoute(
+	agent: AgentConfig,
+	config: SubagentsConfig,
+	ctx: ExtensionContext,
+): DispatchModelRoute {
+	const availableModels = availableModelsInScope(ctx);
+	const mainRef = currentModelRef(ctx);
+	const route = resolveAgentModelRoute({
+		selectedRef: config.agentModels[agent.name],
+		mainRef,
+		availableRefs: availableModels.map(modelRef),
+	});
+	// A `/subagents-setup` override wins; otherwise the role default. No
+	// per-call or frontmatter thinking.
+	const preferred =
+		config.agentThinkingLevels[agent.name] ?? roleThinkingLevel(agent.name);
+	const thinkingLevelForModel = (ref?: string): ThinkingLevel => {
+		const model = ref === mainRef && ctx.model
+			? ctx.model
+			: findModelByRef(availableModels, ref);
+		return resolveThinkingLevel(model, preferred);
+	};
+	return {
+		agent: { ...agent, model: route.primaryRef },
+		mainFallbackRef: route.mainFallbackRef,
+		thinkingLevel: thinkingLevelForModel(route.primaryRef),
+		thinkingLevelForModel,
+	};
+}
+
+/** Project-scoped <projectRoot>/results for a completion's artifacts. */
+export function projectResultsRoot(configPath: string, cwd: string | undefined): string {
+	return join(getProjectRoot(configPath, cwd), "results");
+}

package/src/{tools.ts → lifecycle/tools.ts}

@@ -1,6 +1,6 @@
 /**
- * Thread controls around the subagent runtime: subagent_control (resume) and
- * destructive subagent_stop. There is no status/poll tool — completions carry
+ * Thread controls around the subagent runtime: subagent_control (steer/resume)
+ * and destructive subagent_stop. There is no status/poll tool — completions carry
  * each result (with an on-disk artifact when truncated) and wake the main
  * model, so waiting is never a tool call; the only in-turn block is `wait:
  * true` on a dispatch, for one-shot parents that exit at end of turn.
@@ -11,16 +11,16 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { existsSync } from "node:fs";
 import { Type } from "typebox";
-import { DEFAULT_MAX_RESULT_LINES, loadConfig } from "./config.ts";
+import { DEFAULT_MAX_RESULT_LINES, loadConfig } from "../configuration/config.ts";
 import { removeThreadRecord } from "./durable.ts";
-import { formatCompletionBlock, matchRunIds } from "./format.ts";
-import { emptyUsage } from "./rpc-run.ts";
-import { formatTaskSummary, monitor } from "./monitor.ts";
-import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
+import { formatCompletionBlock, matchRunIds } from "../presentation/format.ts";
+import { emptyUsage } from "../execution/rpc-control.ts";
+import { formatTaskSummary, monitor } from "../presentation/monitor.ts";
+import { persistRecoveryRecords, recoveryRecordFromFinalization } from "../isolation/recovery.ts";
 import type { SubagentRuntime, SubagentThread } from "./runtime.ts";
-import { CONTROL_QUIESCE_TIMEOUT_MS, projectResultsRoot, quiesced } from "./thread-lifecycle.ts";
-import { getResultOutput, isFailedResult, type SingleResult } from "./spawn.ts";
-import type { WorktreeFinalization } from "./worktree.ts";
+import { CONTROL_QUIESCE_TIMEOUT_MS, projectResultsRoot, quiesced } from "./thread-shared.ts";
+import { getResultOutput, type SingleResult } from "../execution/spawn.ts";
+import type { WorktreeFinalization } from "../isolation/worktree.ts";
 
 function renderFirstLine(result: { content?: unknown }, label: string, theme: any): Text {
 	const parts = (result.content ?? []) as Array<{ type: string; text?: string }>;
@@ -34,19 +34,19 @@ function renderFirstLine(result: { content?: unknown }, label: string, theme: an
 
 export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	const SubagentControlParams = Type.Object({
-		action: StringEnum(["resume"] as const, {
+		action: StringEnum(["resume", "steer"] as const, {
 			description: "Control operation for the logical sub-agent thread.",
 		}),
 		id: Type.Integer({ minimum: 1, description: "Stable run id shown by subagent dispatch output." }),
 		objective: Type.Optional(
-			Type.String({ description: "Optional appended objective for resume. Omit to continue the current retained objective." }),
+			Type.String({ description: "Guidance for steer (required and nonblank), or an optional appended objective for resume." }),
 		),
 	});
 
 	pi.registerTool({
 		name: "subagent_control",
 		label: "Subagent Control",
-		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.",
+		description: "Steer an active running child with additional guidance, or resume a parked/settled thread by stable run id.",
 		parameters: SubagentControlParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -64,6 +64,44 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 
 			try {
 				switch (params.action) {
+					case "steer": {
+						const objective = nonBlank(params.objective);
+						if (!objective) {
+							return { content: [{ type: "text", text: "steer objective must be non-blank." }], details: {} };
+						}
+						if (thread.retired) {
+							return { content: [{ type: "text", text: `Run #${thread.id} was retired by subagent_stop and cannot be steered.` }], details: {} };
+						}
+						let unavailable: string | undefined;
+						if (thread.lifecycleOperation === "stop" || thread.state === "stopped") unavailable = "stopped";
+						else if (thread.lifecycleOperation === "park") unavailable = "parking";
+						else if (thread.lifecycleOperation === "settle") unavailable = `settled (${thread.state})`;
+						else if (thread.state === "completed" || thread.state === "failed") unavailable = `settled (${thread.state})`;
+						else if (thread.state === "queued" || thread.state === "resuming") {
+							const phase = thread.control.getPhase();
+							unavailable = phase === "starting" || phase === "retrying" ? phase : thread.state;
+						} else if (thread.state !== "running") unavailable = thread.state;
+						if (unavailable) {
+							return {
+								content: [{ type: "text", text: `Run #${thread.id} is ${unavailable}; only an active running RPC attempt can be steered. No guidance was sent.` }],
+								details: {},
+							};
+						}
+						const steered = await thread.control.steer(objective);
+						if (!steered.accepted) {
+							if (steered.reason === "no-active-attempt") {
+								return { content: [{ type: "text", text: `Run #${thread.id} is marked running but has no active RPC attempt; no guidance was sent.` }], details: {} };
+							}
+							return {
+								content: [{ type: "text", text: `Run #${thread.id} is ${steered.phase}; only an active running RPC attempt can be steered. No guidance was sent.` }],
+								details: {},
+							};
+						}
+						return {
+							content: [{ type: "text", text: `Steered run #${thread.id} with additional in-scope guidance; its original objective is unchanged.` }],
+							details: {},
+						};
+					}
 					case "resume": {
 						if (thread.retired) {
 							return { content: [{ type: "text", text: `Run #${thread.id} was retired by subagent_stop and has no resumable session.` }], details: {} };

package/src/{announcements.ts → presentation/announcements.ts}

@@ -2,10 +2,10 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
-import { FIRST_RUN_SETUP_HINT, loadConfig, saveConfig } from "./config.ts";
-import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
-import { announceRecoveryRecords, relocateRecoveryManifest } from "./recovery.ts";
-import type { SubagentRuntime } from "./runtime.ts";
+import { FIRST_RUN_SETUP_HINT, loadConfig, saveConfig } from "../configuration/config.ts";
+import { availableModelsInScope, filterUnavailableModelOverrides } from "../configuration/models.ts";
+import { announceRecoveryRecords, relocateRecoveryManifest } from "../isolation/recovery.ts";
+import type { SubagentRuntime } from "../lifecycle/runtime.ts";
 import { installActiveRunsStatus } from "./status.ts";
 import { installActiveRunsWidget } from "./widget.ts";
 

package/src/{format.ts → presentation/format.ts}

@@ -4,9 +4,9 @@
  * and run-id matching.
  */
 
-import type { AgentConfig } from "./agents.ts";
+import type { AgentConfig } from "../delegation/agents.ts";
 import { runLabel, shrinkRunLabel } from "./monitor.ts";
-import { emptyUsage } from "./rpc-run.ts";
+import { emptyUsage } from "../execution/rpc-control.ts";
 import {
 	RESULT_LINE_MAX,
 	getResultOutput,
@@ -15,7 +15,7 @@ import {
 	writeResultArtifact,
 	type SingleResult,
 	type UsageStats,
-} from "./spawn.ts";
+} from "../execution/spawn.ts";
 
 export function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
 	return {

package/src/{monitor.ts → presentation/monitor.ts}

@@ -12,8 +12,8 @@
 import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
-import { emptyUsage, type UsageStats } from "./rpc-run.ts";
-import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
+import { emptyUsage, type UsageStats } from "../execution/rpc-control.ts";
+import type { IsolationMode, WorktreeFinalizationStatus } from "../isolation/worktree.ts";
 
 // ---------------------------------------------------------------------------
 // Types

package/src/{widget.ts → presentation/widget.ts}

@@ -29,7 +29,7 @@ import {
 	statusIcon,
 	type RunView,
 } from "./monitor.ts";
-import type { UsageStats } from "./rpc-run.ts";
+import type { UsageStats } from "../execution/rpc-control.ts";
 
 export const SUBAGENTS_WIDGET_ID = "pi-subagents";