@hcflabs/pi-subagent 27.11.0 → 28.1.0

package/extensions/isolated.ts

@@ -1,7 +1,9 @@
-import { basename } from "node:path";
+import { basename, relative, sep } from "node:path";
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
+import { discoverRepos, gitTopLevel, isWithin, resolveRepoTarget, type RepoDiscovery } from "@hcflabs/pi-repo";
+import { Type, type TObject, type TProperties } from "typebox";
 import { capEphemeralSubagentOutput, utf8Prefix, type EphemeralSubagentExecutor } from "../dist/ephemeral.js";
 import {
 	createCanonicalGitRootResolver,
@@ -16,6 +18,7 @@ import { inspectPruneCandidates, listHerdrPanes, removePruneCandidates, type Pru
 import { runProcess as directRunProcess } from "../dist/process.js";
 import { RoleLaunchRuntime, type LaunchRuntimeOptions } from "../dist/launch-runtime.js";
 import { IsolatedRunner, nextIntegrationAction, type ExecutePlan, type OperationContext, type RunResponse } from "../dist/runner.js";
+import { describeFullSuite } from "../dist/full-suite.js";
 import {
 	IdOnlySchema,
 	ResumeRequestParameters,
@@ -29,6 +32,7 @@ import {
 	sameIdentity,
 	StatusOutputSchema,
 	type CheckBatchEvidence,
+	type CheckCommand,
 	type ExecuteRequest,
 	type ExecutionPolicySnapshot,
 	type ModelClass,
@@ -41,6 +45,7 @@ import { FileRunStore } from "../dist/store.js";
 import { workerOutputForMain } from "./result-transport.ts";
 import type { CleanupReport, IsolatedInventory, IsolatedRequest, PrunePlan } from "./subagent-command.ts";
 import type { DiscardPlan } from "../dist/discard.js";
+import { normalizeRepo } from "./workflow.ts";
 
 const LOOKUP_ROOT_TIMEOUT_MS = 5_000;
 const PUBLIC_EVIDENCE_MAX_BYTES = 512;
@@ -61,12 +66,14 @@ export type CreateIsolatedComponents = (options: {
 	executor: EphemeralSubagentExecutor;
 	policy: ExecutionPolicySnapshot;
 	currentPolicy(): ExecutionPolicySnapshot;
+	/** The configured Full suite overrides. Admission reads them after the policy check. */
+	repoSuites?(): Readonly<Record<string, CheckCommand>>;
 	onStateSaved(state: RunState): void;
 }) => IsolatedExtensionComponents;
 
 /** Construct the checked runtime while reusing the unified productive-assignment executor. */
 export const createIsolatedComponents: CreateIsolatedComponents = ({
-	pi, context, executor, policy, currentPolicy, onStateSaved,
+	pi, context, executor, policy, currentPolicy, repoSuites, onStateSaved,
 }) => {
 	const runProcess: DirectProcessRunner = async (command, args, options) => options.stdin === undefined
 		? await pi.exec(command, args, { cwd: options.cwd, signal: options.signal, timeout: options.timeoutMs })
@@ -83,7 +90,7 @@ export const createIsolatedComponents: CreateIsolatedComponents = ({
 		pi,
 		context,
 		resolveRoot,
-		preflightHost: async ({ root }, operation) => await host.preflightHost({ root }, operation),
+		preflightHost: async ({ root, targeted }, operation) => await host.preflightHost({ root, ...(targeted ? { targeted } : {}) }, operation),
 		inspectMainBase: async (input, operation) => await git.inspectMainBase(input, operation),
 	});
 	return {
@@ -96,6 +103,8 @@ export const createIsolatedComponents: CreateIsolatedComponents = ({
 			executor,
 			policy,
 			currentPolicy,
+			undefined,
+			repoSuites,
 		),
 	};
 };
@@ -473,7 +482,8 @@ function toolResult(response: RunResponse, ctx: ExtensionContext, rowsByRequest:
 }
 
 /** Bounded dry-run plan; a route missing from the coordinator report shows as unresolved. */
-export function formatExecutePlan({ request, root, main, routes }: ExecutePlan, hostChecked: boolean): { content: [{ type: "text"; text: string }]; details: unknown } {
+export function formatExecutePlan(plan: ExecutePlan, hostChecked: boolean): { content: [{ type: "text"; text: string }]; details: unknown } {
+	const { request, root, main, routes } = plan;
 	const route = (role: string, modelClass: ModelClass) => {
 		const found = routes.find((candidate) => candidate.role === role && candidate.modelClass === modelClass);
 		return found ? { model: found.model, thinkingLevel: found.thinkingLevel } : undefined;
@@ -495,6 +505,7 @@ export function formatExecutePlan({ request, root, main, routes }: ExecutePlan,
 			...(task.kind === "changeset" ? [`   checks: ${task.checks.map(formatCheckCommand).join("; ")}`,
 				...(task.judgment ? [`   judgment: ${label(task.judgment.role, task.judgment.modelClass)}`] : [])] : []),
 		].join("\n")),
+		...(plan.fullSuite ? [`Full suite: ${describeFullSuite(plan.fullSuite)}`] : []),
 		`Final checks: ${request.finalChecks.map(formatCheckCommand).join("; ") || "none"}`,
 		...(request.finalJudgment ? [`Final judgment: ${label(request.finalJudgment.role, request.finalJudgment.modelClass)}`] : []),
 		...notChecked.map((reason) => `Not checked: ${reason}.`),
@@ -507,16 +518,39 @@ export function formatExecutePlan({ request, root, main, routes }: ExecutePlan,
 				...route(task.role, task.modelClass), dependsOn: task.dependsOn, contextFrom: task.contextFrom,
 				...(task.kind === "changeset" ? { checks: task.checks, ...(task.judgment ? { judgment: { ...task.judgment, ...route(task.judgment.role, task.judgment.modelClass) } } : {}) } : {}) })),
 			finalChecks: request.finalChecks,
+			...(plan.fullSuite ? { fullSuite: plan.fullSuite } : {}),
 			...(request.finalJudgment ? { finalJudgment: { ...request.finalJudgment, ...route(request.finalJudgment.role, request.finalJudgment.modelClass) } } : {}),
 			notChecked,
 		},
 	};
 }
 
+const RepoParameter = Type.Optional(Type.String({
+	minLength: 1,
+	description: "Repository target of the request: the same repo that delegate_task used, as a path relative to the Pi working directory. Omit it when the request runs in the checkout of the Pi working directory.",
+}));
+
+/** Add the optional `repo` selector to a flat tool schema. The selector is not part of the durable request. */
+function withRepo<P extends TProperties>(schema: TObject<P>): TObject<P & { repo: typeof RepoParameter }> {
+	return Type.Object({ ...schema.properties, repo: RepoParameter }, { additionalProperties: false }) as unknown as TObject<P & { repo: typeof RepoParameter }>;
+}
+
+/** Parse the request without `repo`, then add `repo` back as a separate selector. */
+function parseWithRepo<T extends object>(parse: (value: unknown) => T): (value: unknown) => T & { repo?: string } {
+	return (value) => {
+		if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, "repo")) return parse(value);
+		const { repo, ...rest } = value as Record<string, unknown>;
+		if (typeof repo !== "string") throw new Error("repo must be a relative path.");
+		// Normalize like delegate_task, so a recovery call selects the same Repository target.
+		return { ...parse(rest), repo: normalizeRepo(repo, "repo") };
+	};
+}
+
 export interface IsolatedSurface {
 	/** Dry run of execute: validates and resolves without durable state or Herdr calls. */
-	plan(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof formatExecutePlan>>;
-	execute(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof toolResult>>;
+	/** `repo` selects a Repository target below the Pi working directory. */
+	plan(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext, repo?: string): Promise<ReturnType<typeof formatExecutePlan>>;
+	execute(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext, repo?: string): Promise<ReturnType<typeof toolResult>>;
 	inventory(cwd: string, current?: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
 	prunePlan(cwd: string): Promise<PrunePlan>;
@@ -533,6 +567,8 @@ export interface RegisterIsolatedOptions {
 	executor: EphemeralSubagentExecutor;
 	policy: ExecutionPolicySnapshot;
 	currentPolicy(): ExecutionPolicySnapshot;
+	/** The configured Full suite overrides for isolated changesets. */
+	repoSuites?(): Readonly<Record<string, CheckCommand>>;
 	/** Report new config issues, and throw when the config now blocks delegation, before each deferred Role launch. */
 	beforeRoleLaunch?(ctx: ExtensionContext): void;
 	componentsFactory?: CreateIsolatedComponents;
@@ -566,6 +602,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		executor: options.executor,
 		policy: options.policy,
 		currentPolicy: options.currentPolicy,
+		...(options.repoSuites ? { repoSuites: options.repoSuites } : {}),
 		onStateSaved: (state) => {
 			savedRevision += 1;
 			for (const listener of stateListeners) listener(state);
@@ -575,14 +612,20 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			}
 		},
 	});
-	const lookupRoot = async (cwd: string, signal?: AbortSignal): Promise<string> => {
+	/** The canonical checkout root: the Repository target `repo` below `cwd`, or the checkout that contains `cwd`. */
+	const lookupRoot = async (cwd: string, signal?: AbortSignal, repo?: string): Promise<string> => {
 		const startedAt = Date.now();
 		const context: OperationContext = {
 			signal: signal ?? new AbortController().signal,
 			timeoutMs: LOOKUP_ROOT_TIMEOUT_MS,
 			deadline: startedAt + LOOKUP_ROOT_TIMEOUT_MS,
 		};
-		return await getComponents().resolveRoot(cwd, context);
+		if (repo === undefined) return await getComponents().resolveRoot(cwd, context);
+		const target = (await resolveRepoTarget(cwd, repo, { signal: context.signal, timeoutMs: LOOKUP_ROOT_TIMEOUT_MS })).root;
+		const root = await getComponents().resolveRoot(target, context);
+		// The checkout can change between two Git probes. Use only the root that the target validation proved.
+		if (root !== target) throw new Error(`Repository target ${repo} resolved to ${target}, but Git now reports ${root}. Nothing was changed; retry.`);
+		return root;
 	};
 
 	pi.on("session_start", (_event, ctx) => {
@@ -744,12 +787,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		name: "subagent_status",
 		label: "Subagent status",
 		description: "Read one durable isolated request without reconciling or changing resources.",
-		parameters: IdOnlySchema,
-		prepareArguments: parseIdOnly,
+		parameters: withRepo(IdOnlySchema),
+		prepareArguments: parseWithRepo(parseIdOnly),
 		outputSchema: StatusOutputSchema,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
-			const root = await lookupRoot(ctx.cwd, signal);
+			const root = await lookupRoot(ctx.cwd, signal, params.repo);
 			const response = await getComponents().runner.status(params.id, root, signal);
 			const result = toolResult(response, ctx, workspaceRowsByRequest);
 			const content = [{ type: "text" as const, text: `${result.content[0]!.text}${failedReviewText(response.state)}` }];
@@ -761,12 +804,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		name: "subagent_resume",
 		label: "Subagent resume",
 		description: "Resume one unfinished isolated request without resetting its recorded policy or correction count. For a retry that sends a same-worker correction, optional instruction (at most 32000 characters) is appended to that prompt as Main's instruction after the saved check or review failure; use it to name the exact fixes, including the review findings the worker must address. Other actions reject instruction.",
-		parameters: ResumeRequestParameters,
-		prepareArguments: parseResumeRequest,
+		parameters: withRepo(ResumeRequestParameters),
+		prepareArguments: parseWithRepo(parseResumeRequest),
 		exposure: "model-only",
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(_toolCallId, { repo, ...params }, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
-			const root = await lookupRoot(ctx.cwd, signal);
+			const root = await lookupRoot(ctx.cwd, signal, repo);
 			return await startInSession(params.id, root, signal, ctx,
 				(state) => state.recovery?.kind === "resume" && state.recovery.action === params.action
 					&& (!("taskId" in params) || state.recovery.taskId === params.taskId),
@@ -777,12 +820,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		name: "subagent_stage",
 		label: "Subagent stage",
 		description: "Main stages/resolves an exact candidate, or rejects/revises one. Rejection of a staged candidate freezes the old generation; explicitly restage chosen candidates in a new generation. Never writes Main.",
-		parameters: StageRequestSchema,
-		prepareArguments: parseStageRequest,
+		parameters: withRepo(StageRequestSchema),
+		prepareArguments: parseWithRepo(parseStageRequest),
 		exposure: "model-only",
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(_toolCallId, { repo, ...params }, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
-			const root = await lookupRoot(ctx.cwd, signal);
+			const root = await lookupRoot(ctx.cwd, signal, repo);
 			return toolResult(await getComponents().runner.stage(params, root, signal), ctx, workspaceRowsByRequest);
 		},
 	});
@@ -790,12 +833,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		name: "subagent_integrate",
 		label: "Subagent integrate",
 		description: "Main advances staged dependents, refreshes after clean Main drift or evidence-less validation failure, validates in the background, corrects, promotes, reconciles interrupted validation/promotion, cleans up promoted resources, or explicitly releases rejected/superseded owned resources. Never replays an uncertain mutation.",
-		parameters: IntegrationActionParameters,
-		prepareArguments: parseIntegrationAction,
+		parameters: withRepo(IntegrationActionParameters),
+		prepareArguments: parseWithRepo(parseIntegrationAction),
 		exposure: "model-only",
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(_toolCallId, { repo, ...params }, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
-			const root = await lookupRoot(ctx.cwd, signal);
+			const root = await lookupRoot(ctx.cwd, signal, repo);
 			if (params.action === "validate") {
 				return await startInSession(params.id, root, signal, ctx,
 					(state) => {
@@ -818,18 +861,87 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		name: "subagent_abort",
 		label: "Subagent abort",
 		description: "Abort an isolated request; reject and release retained candidates and integration checkouts first unless their checkouts and branches are proved absent. Terminate only exact owned workers. Repeat abort to reconcile cleanup of unchanged allocations; preserve dirty or committed work.",
-		parameters: IdOnlySchema,
-		prepareArguments: parseIdOnly,
+		parameters: withRepo(IdOnlySchema),
+		prepareArguments: parseWithRepo(parseIdOnly),
 		exposure: "model-only",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
-			const root = await lookupRoot(ctx.cwd, signal);
+			const root = await lookupRoot(ctx.cwd, signal, params.repo);
 			return toolResult(await getComponents().runner.abort(params.id, root, signal), ctx, workspaceRowsByRequest);
 		},
 	});
+	/** Recovery report lines for one canonical checkout root. */
+	const recoveryLines = async (root: string): Promise<string[]> => {
+		const { requests, invalidIds, leaseBusy } = await getComponents().runner.recoverRepository(root);
+		const lines = [
+			`Pi Subagent recovery in ${root}: ${leaseBusy ? "productive lease is live; no state changed" : "orphaned interruptions classified; no work replayed"}.`,
+			...(requests.length ? requests.map((response) => {
+				const state = response.state;
+				const blockers = state.tasks.flatMap((task) => [
+					...(task.failure ? [`${task.taskId}: ${boundedPublicText(task.failure)}`] : []),
+					...(task.kind === "changeset" && task.attempts.some((attempt) => attempt.prompts.some((prompt) => prompt.status === "ambiguous"))
+						? [`${task.taskId}: ambiguous worker prompt; do not replay`] : []),
+				]);
+				const generation = state.integration.generations.at(-1);
+				const readyCandidates = state.integration.candidates.filter((candidate) => candidate.worker === "retained" && !candidate.decision);
+				return [
+					`${state.request.id}: ${state.status}; Main ${response.main?.status ?? "not checked"}.`,
+					...blockers.map((blocker) => `  Blocker: ${blocker}`),
+					...(state.final.failure ? [`  Final blocker: ${boundedPublicText(state.final.failure)}`] : []),
+					...(generation?.failure ? [`  Integration blocker: ${boundedPublicText(generation.failure)}`] : []),
+					...(state.status !== "completed" && readyCandidates.length ? [`  ${readyCandidates.length} retained candidate(s); Main selects exact candidates with subagent_stage after subagent_status.`] : []),
+					...(state.status === "completed" ? ["  Retained resources after completion; inspect subagent_status for guarded cleanup."] : []),
+					...(generation ? [`  Generation ${generation.number}: ${generation.status}; inspect subagent_status before any subagent_integrate action.`] : []),
+					...(!leaseBusy && response.continuation ? [`  Reported next action: subagent_resume ${JSON.stringify(response.continuation)}.`] : []),
+				].join("\n");
+		}) : ["No unfinished or retained isolated requests."]),
+		...(invalidIds.length ? [`Unreadable state IDs (preserved; inspect with their compatible owner): ${invalidIds.map((id) => JSON.stringify(id)).join(", ")}.`] : []),
+		leaseBusy ? "Wait for the active productive run; use subagent_status to inspect its current state. No work was taken over."
+			: "Main: inspect subagent_status for exact identities and blockers before deciding stage, promote, resume, or guarded release. No worker prompt, merge, promotion, or cleanup was replayed.",
+		];
+		return lines;
+	};
+	/** Report lines for discovery issues and truncation, because an incomplete search cannot prove absence. */
+	const discoveryWarnings = (found: RepoDiscovery): string[] => [
+		...(found.truncated ? [`Repository discovery below ${found.base} stopped at a limit; some repositories were not examined.`] : []),
+		...found.issues.slice(0, 20).map(({ path, reason }) => `Repository discovery could not examine ${path}: ${boundedPublicText(reason)}`),
+		...(found.issues.length > 20 ? [`${found.issues.length - 20} more repository discovery issues omitted.`] : []),
+	];
+	/** Read-only inventory across the Repository targets below a parent directory that is not a Git repository. */
+	const childInventory = async (cwd: string, current: () => boolean = () => true): Promise<IsolatedInventory> => {
+		const found = await discoverRepos(cwd);
+		const requests: IsolatedRequest[] = [];
+		const invalidIds: string[] = [];
+		const selectorOf = (root: string) => found.repos.find((item) => item.root === root)?.repo
+			?? (isWithin(found.base, root) ? relative(found.base, root).split(sep).join("/") : root);
+		for (const { repo, root } of found.repos) {
+			if (!current()) throw new Error("Session or branch changed; reopen /subagent.");
+			const listed = await getComponents().runner.listRequests(root);
+			const leaseLive = await getComponents().runner.hasProductiveRunLease(root);
+			for (const request of listed.requests) requests.push({ ...request, root: request.root ?? root, repo, leaseLive, checkout: root });
+			invalidIds.push(...listed.invalidIds.map((id) => `${repo}/${id}`));
+		}
+		// One scan of the whole state store. An orphan's primary checkout is live, so Git commands run there.
+		const orphans = await getComponents().runner.listAllOrphanRequests();
+		for (const { primary, ...request } of orphans.requests) {
+			if (!isWithin(found.base, primary)) continue;
+			requests.push({ ...request, repo: selectorOf(primary), leaseLive: false, checkout: primary });
+		}
+		invalidIds.push(...orphans.invalidIds);
+		return { root: found.base, leaseLive: requests.some((request) => request.leaseLive), requests,
+			invalidIds: [...new Set(invalidIds)], warnings: discoveryWarnings(found) };
+	};
 	return {
 		async inventory(cwd, current) {
-			const root = await lookupRoot(cwd);
+			let root: string;
+			try {
+				root = await lookupRoot(cwd);
+			} catch (error) {
+				// Outside a Git repository, list the requests of each Repository target below cwd.
+				// Any other failure, such as a Git timeout, stays a failure.
+				if (await gitTopLevel(cwd).then((top) => top !== undefined, () => true)) throw error;
+				return await childInventory(cwd, current);
+			}
 			const revision = savedRevision;
 			const { requests, invalidIds, states } = await getComponents().runner.listRequests(root);
 			if (current?.() && !sessionClosed && revision === savedRevision) {
@@ -846,44 +958,42 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			return { root, leaseLive, requests: [...requests, ...orphans.requests], invalidIds: [...new Set([...invalidIds, ...orphans.invalidIds])] };
 		},
 		async recover(cwd) {
-			const root = await lookupRoot(cwd);
-			const { requests, invalidIds, leaseBusy } = await getComponents().runner.recoverRepository(root);
-			const lines = [
-				`Pi Subagent recovery in ${root}: ${leaseBusy ? "productive lease is live; no state changed" : "orphaned interruptions classified; no work replayed"}.`,
-				...(requests.length ? requests.map((response) => {
-					const state = response.state;
-					const blockers = state.tasks.flatMap((task) => [
-						...(task.failure ? [`${task.taskId}: ${boundedPublicText(task.failure)}`] : []),
-						...(task.kind === "changeset" && task.attempts.some((attempt) => attempt.prompts.some((prompt) => prompt.status === "ambiguous"))
-							? [`${task.taskId}: ambiguous worker prompt; do not replay`] : []),
-					]);
-					const generation = state.integration.generations.at(-1);
-					const readyCandidates = state.integration.candidates.filter((candidate) => candidate.worker === "retained" && !candidate.decision);
-					return [
-						`${state.request.id}: ${state.status}; Main ${response.main?.status ?? "not checked"}.`,
-						...blockers.map((blocker) => `  Blocker: ${blocker}`),
-						...(state.final.failure ? [`  Final blocker: ${boundedPublicText(state.final.failure)}`] : []),
-						...(generation?.failure ? [`  Integration blocker: ${boundedPublicText(generation.failure)}`] : []),
-						...(state.status !== "completed" && readyCandidates.length ? [`  ${readyCandidates.length} retained candidate(s); Main selects exact candidates with subagent_stage after subagent_status.`] : []),
-						...(state.status === "completed" ? ["  Retained resources after completion; inspect subagent_status for guarded cleanup."] : []),
-						...(generation ? [`  Generation ${generation.number}: ${generation.status}; inspect subagent_status before any subagent_integrate action.`] : []),
-						...(!leaseBusy && response.continuation ? [`  Reported next action: subagent_resume ${JSON.stringify(response.continuation)}.`] : []),
-					].join("\n");
-			}) : ["No unfinished or retained isolated requests."]),
-			...(invalidIds.length ? [`Unreadable state IDs (preserved; inspect with their compatible owner): ${invalidIds.map((id) => JSON.stringify(id)).join(", ")}.`] : []),
-			leaseBusy ? "Wait for the active productive run; use subagent_status to inspect its current state. No work was taken over."
-				: "Main: inspect subagent_status for exact identities and blockers before deciding stage, promote, resume, or guarded release. No worker prompt, merge, promotion, or cleanup was replayed.",
-			];
-			return boundedReport(lines, "recovery report lines omitted; use subagent_status for exact request evidence.");
+			let root: string;
+			try {
+				root = await lookupRoot(cwd);
+			} catch (error) {
+				if (await gitTopLevel(cwd).then((top) => top !== undefined, () => true)) throw error;
+				// Outside a Git repository, recover each Repository target that has saved requests.
+				const found = await discoverRepos(cwd);
+				const lines: string[] = [];
+				for (const { repo, root: child } of found.repos) {
+					const listed = await getComponents().runner.listRequests(child);
+					if (!listed.requests.length && !listed.invalidIds.length) continue;
+					lines.push(`repo ${repo}:`, ...await recoveryLines(child));
+				}
+				const warnings = discoveryWarnings(found);
+				// An incomplete discovery is not proof that no request exists.
+				if (!lines.length) lines.push(warnings.length ? `No isolated requests in the ${found.repos.length} repositories that discovery examined below ${found.base}.`
+					: `No isolated requests in the ${found.repos.length} repositories below ${found.base}.`);
+				lines.push(...warnings);
+				return boundedReport(lines, "recovery report lines omitted; use subagent_status for exact request evidence.");
+			}
+			return boundedReport(await recoveryLines(root), "recovery report lines omitted; use subagent_status for exact request evidence.");
 		},
 		async discardPlan(cwd, request) {
-			return await getComponents().runner.discardPlan(cwd, request.id, request.directory, {
+			// A request listed from a parent directory runs Git in a live checkout of its own repository.
+			if (request.checkout !== undefined) cwd = request.checkout;
+			const plan = await getComponents().runner.discardPlan(cwd, request.id, request.directory, {
 				panes: () => listHerdrPanes(cwd), current: () => !sessionClosed,
 				blocked: async () => jobOwners.has(`${request.root}\0${request.id}`) ? "A local job is active for this request." : undefined,
 			});
+			return request.checkout === undefined ? plan : { ...plan, checkout: request.checkout };
 		},
 		async discard(cwd, plan, current) {
 			requireCurrent(current);
+			// The plan keeps the live checkout that it used. The saved request root can be removed.
+			const checkout = (plan as DiscardPlan & { checkout?: string }).checkout;
+			if (checkout !== undefined) cwd = checkout;
 			const removals = await getComponents().runner.discard(cwd, plan, {
 				panes: () => listHerdrPanes(cwd), current: () => current() && !sessionClosed,
 				blocked: async () => jobOwners.has(`${plan.root}\0${plan.requestId}`) ? "A local job is active for this request." : undefined,
@@ -925,21 +1035,25 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			requireCurrent(current);
 			return getComponents().runner.drainFollowups(root, requestId, taskId);
 		},
-		async plan(request, signal, ctx) {
+		async plan(request, signal, ctx, repo) {
 			latestCtx = ctx;
 			latestContext();
-			const root = await lookupRoot(ctx.cwd, signal);
+			const root = await lookupRoot(ctx.cwd, signal, repo);
 			if (jobOwners.has(`${root}\0${request.id}`)) throw new Error(`Pi Subagent request ${request.id} is already active in this session runtime.`);
-			return formatExecutePlan(await getComponents().runner.plan(request, ctx.cwd, signal), false);
+			const cwd = repo === undefined ? ctx.cwd : root;
+			return formatExecutePlan(await (repo === undefined ? getComponents().runner.plan(request, cwd, signal) : getComponents().runner.plan(request, cwd, signal, { targeted: true })), false);
 		},
-		async execute(request, signal, ctx) {
+		async execute(request, signal, ctx, repo) {
 			latestCtx = ctx;
 			latestContext();
-			const root = await lookupRoot(ctx.cwd, signal);
+			const root = await lookupRoot(ctx.cwd, signal, repo);
+			// The runner resolves the same root again from this cwd. A Repository target is its own root.
+			const cwd = repo === undefined ? ctx.cwd : root;
 			return await startInSession(request.id, root, signal, ctx,
 				(state) => state.status === "pending" && state.createdAt === state.updatedAt
 					&& state.tasks.every((task) => task.status === "pending" && task.attempts.length === 0),
-				(runSignal) => getComponents().runner.execute(request, ctx.cwd, runSignal));
+				(runSignal) => repo === undefined ? getComponents().runner.execute(request, cwd, runSignal)
+					: getComponents().runner.execute(request, cwd, runSignal, { targeted: true }));
 		},
 	};
 }

package/extensions/subagent-command.ts

@@ -50,6 +50,12 @@ export interface IsolatedRequest {
 	/** Saved state address for a removed parent checkout. */
 	directory?: string;
 	root?: string;
+	/** The Repository target selector, when /subagent runs in a parent directory of repositories. */
+	repo?: string;
+	/** The productive lease state of this request's root, when the inventory spans several roots. */
+	leaseLive?: boolean;
+	/** A live checkout of the request's repository for Git commands, when the inventory spans several roots. */
+	checkout?: string;
 	orphaned?: boolean;
 	name: string;
 	status: string;
@@ -61,6 +67,8 @@ export interface IsolatedInventory {
 	leaseLive: boolean;
 	requests: readonly IsolatedRequest[];
 	invalidIds: readonly string[];
+	/** Incomplete inventory evidence, such as discovery issues or truncation. */
+	warnings?: readonly string[];
 }
 
 export type { PruneItem };
@@ -192,7 +200,7 @@ const summary = (text: string, max = 60): string => {
 	return chars.length > max ? `${chars.slice(0, max - 1).join("")}…` : chars.join("");
 };
 // Identity and status first so clipping cuts only the goal summary.
-const isolatedLabel = ({ id, status, name }: IsolatedRequest): string => `${id} · ${status} · ${summary(name)}`;
+const isolatedLabel = ({ id, repo, status, name }: IsolatedRequest): string => `${id}${repo ? ` · repo ${repo}` : ""} · ${status} · ${summary(name)}`;
 const completed = (status: string) => [...TERMINAL_RUN_STATUSES, "success", "failed", "failure", "integrated"].includes(status);
 const priority = (status: string) => /attention|blocked|retained|failed/i.test(status) ? 0 : completed(status) ? 2 : 1;
 // Recorded-only and unverified work is uncertain, not active.
@@ -310,7 +318,7 @@ export function workingReport(direct: readonly DirectTask[], inventory: Isolated
 	}
 	for (const request of inventory?.requests ?? []) {
 		const active = !request.orphaned && ["pending", "running"].includes(request.status);
-		if (active && inventory!.leaseLive) working.push({ text: isolatedLabel(request) });
+		if (active && (request.leaseLive ?? inventory!.leaseLive)) working.push({ text: isolatedLabel(request) });
 		else if (active) attention.push({ text: `${isolatedLabel(request)} · interrupted; run /subagent recover` });
 		else if (request.status === "needs_attention" || /retained/.test(request.status)) attention.push({ text: isolatedLabel(request) });
 		else if (request.orphaned && /unverified/.test(request.status)) unverified.push({ text: isolatedLabel(request) });
@@ -558,6 +566,7 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				if (report) deliver(ctx, workingReport(direct, inventory));
 				report = false;
 				if (unavailable) ctx.ui.notify(`Isolated inventory unavailable (${unavailable}). Direct branch recovery remains available; check the canonical Git checkout/configuration.`, "warning");
+				for (const warning of inventory?.warnings ?? []) ctx.ui.notify(warning, "warning");
 				if (inventory?.invalidIds.length) for (const id of inventory.invalidIds) ctx.ui.notify(`Unreadable isolated state ID: ${JSON.stringify(id)}. Preserve this file; inspect the state store before making changes.`, "warning");
 				type Selection = { kind: "direct"; task: DirectTask } | { kind: "isolated"; request: IsolatedRequest; root: string } | { kind: "refresh" } | { kind: "history" } | { kind: "many" } | { kind: "close" };
 				// A header row selects Refresh; rows sort by status priority within their group.
@@ -565,7 +574,7 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 					items.length ? [{ label: `── ${title} (${items.length}) ──`, value: { kind: "refresh" } },
 						...[...items].sort((a, b) => priority(a.status) - priority(b.status)).map(choice)] : [];
 				const requests = (inventory?.requests ?? []).filter((request) => history || !completed(request.status) || /retained/i.test(request.status));
-				const isolatedChoice = (request: IsolatedRequest): Choice<Selection> => ({ label: `  ${glyph(request.status)} ${isolatedLabel(request)}`, value: { kind: "isolated", request, root: inventory!.root } });
+				const isolatedChoice = (request: IsolatedRequest): Choice<Selection> => ({ label: `  ${glyph(request.status)} ${isolatedLabel(request)}`, value: { kind: "isolated", request, root: request.root ?? inventory!.root } });
 				// One row per workflow; new records keep opaque IDs in details. Status is last so clipping preserves the reference.
 				const directChoice = (task: DirectTask): Choice<Selection> => ({ label: `  ${glyph(task.status)} ${directLabel(task)} · ${task.status}${costSuffix(task.cost)}${task.workers.length || task.name === task.id ? "" : ` · ${task.id}`}`, value: { kind: "direct", task } });
 				const groups = [

package/extensions/subagent.ts

@@ -255,6 +255,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		executor,
 		policy: initialPolicy,
 		currentPolicy,
+		// Admission reads these after currentPolicy, which throws for a disabled config.
+		repoSuites: () => { const loaded = configStore.loadSync(); return loaded.status === "ok" ? loaded.value.repoSuites : {}; },
 		beforeRoleLaunch,
 	});
 	let directSequence = 0;
@@ -701,7 +703,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			try {
 				const parsed = parseDelegateTask(args);
 				const dryRun = parsed.dryRun ? { dryRun: true } : {};
-				if (parsed.mode === "isolated") return { ...parsed.request, ...dryRun };
+				if (parsed.mode === "isolated") return { ...parsed.request, ...(parsed.repo === undefined ? {} : { repo: parsed.repo }), ...dryRun };
 				const workflow = parsed.workflow;
 				if (workflow.mode === "single") return { mode: "direct" as const, ...workflow.delegations[0], ...dryRun };
 				if (workflow.mode === "parallel") return { mode: "direct" as const, tasks: workflow.delegations, ...dryRun };
@@ -714,7 +716,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			reportConfig(ctx);
 			const parsed = parseDelegateTask(params);
 			if (parsed.mode === "isolated") {
-				return parsed.dryRun ? await isolatedSurface.plan(parsed.request, signal, ctx) : await isolatedSurface.execute(parsed.request, signal, ctx);
+				return parsed.dryRun ? await isolatedSurface.plan(parsed.request, signal, ctx, parsed.repo) : await isolatedSurface.execute(parsed.request, signal, ctx, parsed.repo);
 			}
 			const workflow = parsed.workflow;
 			const catalog = loadRoleCatalog();

package/extensions/workflow.ts

@@ -35,7 +35,7 @@ const ContinueFromSchema = Type.String({ pattern: "^D[1-9][0-9]*\\.[1-9][0-9]*$"
 
 const RepoSchema = Type.String({
 	minLength: 1,
-	description: "Optional Repository target: a child Git repository as a path relative to the Pi working directory, such as team/service. The worker runs there, and admission reserves that checkout. A task value overrides the request value. Omit it to use the Pi working directory. Use subagent_repos to list targets.",
+	description: "Optional Repository target: a child Git repository as a path relative to the Pi working directory, such as team/service. Direct workers run there, and admission reserves that checkout; a direct task value overrides the request value. Mode isolated accepts it only on the request, and the whole graph, its state, and its promotion use that repository. Omit it to use the Pi working directory. Use subagent_repos to list targets.",
 });
 
 const PathsSchema = Type.Array(Type.String({ minLength: 1 }), {
@@ -94,7 +94,8 @@ export type ParsedWorkflow =
 	| { mode: "single"; delegations: [Delegation] }
 	| { mode: "parallel"; delegations: Delegation[] }
 	| { mode: "chain"; delegations: Delegation[] };
-export type ParsedDelegateTask = ({ mode: "direct"; workflow: ParsedWorkflow } | { mode: "isolated"; request: ExecuteRequest }) & { dryRun: boolean };
+/** An isolated `repo` selects the one Repository target of the whole graph. It is not part of the durable request. */
+export type ParsedDelegateTask = ({ mode: "direct"; workflow: ParsedWorkflow } | { mode: "isolated"; request: ExecuteRequest; repo?: string }) & { dryRun: boolean };
 
 type DirectInput = Static<typeof DirectWorkflowSchema>;
 const DELEGATION_KEYS = ["role", "name", "task", "access", "paths", "continueFrom", "kind", "model", "modelClass"] as const;
@@ -122,7 +123,7 @@ function normalizePaths(value: Static<typeof DelegationSchema>, path: string): s
 }
 
 /** Check the selector shape here. Admission and launch resolve it against the Pi working directory. */
-function normalizeRepo(value: string, path: string): string {
+export function normalizeRepo(value: string, path: string): string {
 	const normalized = text(value, path);
 	if (/[\u0000-\u001f\u007f-\u009f]/.test(normalized) || normalized.startsWith("/") || normalized.split(/[\\/]/).includes("..")) {
 		throw new Error(`${path} must be a relative path without control characters or .. components.`);
@@ -207,8 +208,10 @@ export function parseDelegateTask(value: unknown): ParsedDelegateTask {
 		value = rest;
 	}
 	if (value && typeof value === "object" && !Array.isArray(value) && (value as { mode?: unknown }).mode === "isolated") {
-		if (Object.hasOwn(value, "repo")) throw new Error("mode isolated does not accept repo yet. Start Pi in the repository, or use mode direct.");
-		return { mode: "isolated", request: parseExecuteRequest(value), dryRun };
+		const { repo, ...request } = value as Record<string, unknown>;
+		if (repo === undefined) return { mode: "isolated", request: parseExecuteRequest(request), dryRun };
+		if (typeof repo !== "string") throw new Error("repo must be a relative path.");
+		return { mode: "isolated", request: parseExecuteRequest(request), repo: normalizeRepo(repo, "repo"), dryRun };
 	}
 	return { mode: "direct", workflow: parseWorkflow(value), dryRun };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hcflabs/pi-subagent",
-  "version": "27.11.0",
+  "version": "28.1.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent/SKILL.md

@@ -30,7 +30,7 @@ To build on a finished direct worker, add `continueFrom` with its reference (suc
 
 # Isolated requests
 
-Give the request a unique ID and goal. Give each task a unique ID, kind, Role, model class, bounded requirements, deliverable, `dependsOn`, and `contextFrom`. Changesets require focused task checks, and a graph containing changesets requires final checks. The root must have a `package.json` test script; `pnpm test` is added to final checks if missing and runs against the combined tip before Main promotion. Text context may name only completed text tasks, preserves declared order, and implies a scheduling dependency; do not repeat an edge in `dependsOn` and `contextFrom`.
+Give the request a unique ID and goal. Give each task a unique ID, kind, Role, model class, bounded requirements, deliverable, `dependsOn`, and `contextFrom`. Changesets require focused task checks, and a graph containing changesets requires final checks. Admission adds the repository's Full suite to final checks if missing: the `repoSuites` config entry, `pnpm test` for a root `package.json` test script, or `make test` for a Makefile `test` target. The suite runs against the combined tip before Main promotion. If no suite exists, tell the user to add one or configure `repoSuites`. Text context may name only completed text tasks, preserves declared order, and implies a scheduling dependency; do not repeat an edge in `dependsOn` and `contextFrom`.
 
 Every changeset becomes ready automatically after preliminary checks pass. While a locally owned changeset task is actively working, the user may open `/subagent` to queue bounded same-worker revisions or withdraw all still-pending instructions into the native editor and submit one replacement. Cancellation after withdrawal leaves the originals removed; already-claimed instructions cannot be recalled. Each revision must produce a new clean commit and rerun preliminary checks. If a worker's turn ends with uncommitted changes, the runner sends it one commit reminder per attempt; this uses no correction, and a worktree still dirty afterwards needs attention. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for sibling workers. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.