@hcflabs/pi-subagent 28.0.0 → 28.1.0

package/README.md

@@ -108,7 +108,11 @@ When Pi runs in a parent directory that holds many repositories, set `repo` to s
 
 The worker opens in the current Herdr workspace with the Repository target as its working directory. Change reports and stale-read checks use that checkout, and each result names its `repo`. A write request reserves the checkout of each target at one time, so writers in different repositories can run together. When Pi runs in a parent directory that is not a Git repository, each Main call that can write covers the whole parent. Such a call waits while a direct writer owns the checkout of any Repository target in it. Main can still read files and use `subagent_repos`.
 
-Isolated mode does not accept `repo` yet.
+An isolated request accepts one `repo` for the whole graph. Tasks cannot select another repository. The request then uses the Repository target as its checkout. State, worker worktrees, validation, and promotion belong to that repository. The Pi working directory does not change.
+
+Your Herdr workspace can belong to another checkout or to none. Herdr opens the primary workspace of the target when it opens the first worker worktree, and it does not close that workspace later. Pass the same `repo` to `subagent_status`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort`.
+
+Run `/subagent` in a parent directory that is not a Git repository. It lists the isolated requests of each Repository target below it, with their `repo`. `/subagent recover` recovers each Repository target that has saved requests. `/subagent prune` still needs a Git checkout.
 
 To continue a finished worker, add `"continueFrom": "D7.1"` with the same `role`. This opens a new tab with the saved conversation and a new reference. Continue the newest reference from the original checkout and workspace. For a worker that ran with `repo`, select the same `repo`. For eligibility and stop behavior, see [Continue or stop one direct worker](./docs/orchestration.md#continue-or-stop-one-direct-worker).
 

package/dist/herdr-runtime.d.ts

@@ -38,9 +38,15 @@ export declare class HerdrHostRuntime implements HostRuntime {
     private readonly lsofCommand;
     private readonly executionBudget?;
     constructor(options: HerdrHostRuntimeOptions);
-    /** Fail-closed Herdr caller/capability gate. This method creates no state or host resource. */
+    /**
+     * Fail-closed Herdr caller/capability gate. This method creates no state or host resource.
+     * Without `targeted`, the caller's workspace must be the checkout `root`. With `targeted`, `root` is a
+     * Repository target, and the caller's workspace can belong to any checkout or to none.
+     * Herdr opens the primary workspace of the target when it opens an owned worktree.
+     */
     preflightHost(input: {
         root: string;
+        targeted?: boolean;
     }, context: OperationContext): Promise<void>;
     planHostAllocation(input: {
         readonly requestId: ExecuteRequest["id"];

package/dist/herdr-runtime.js

@@ -270,7 +270,12 @@ export class HerdrHostRuntime {
         this.lsofCommand = options.lsofCommand ?? "lsof";
         this.executionBudget = options.executionBudget;
     }
-    /** Fail-closed Herdr caller/capability gate. This method creates no state or host resource. */
+    /**
+     * Fail-closed Herdr caller/capability gate. This method creates no state or host resource.
+     * Without `targeted`, the caller's workspace must be the checkout `root`. With `targeted`, `root` is a
+     * Repository target, and the caller's workspace can belong to any checkout or to none.
+     * Herdr opens the primary workspace of the target when it opens an owned worktree.
+     */
     async preflightHost(input, context) {
         context.signal.throwIfAborted();
         if (this.env.HERDR_ENV !== "1")
@@ -306,6 +311,11 @@ export class HerdrHostRuntime {
         const workspaceId = exactString(pane.workspace_id, "Herdr current workspace_id");
         const workspaceResponse = await this.herdr.json(["workspace", "get", workspaceId], this.processOptions(root, context, HERDR_OPERATION_CAP_MS));
         const workspace = parseWorkspaceInfo(workspaceResponse, workspaceId);
+        if (input.targeted) {
+            // The worker worktrees open from the primary checkout of the target, not from the caller's workspace.
+            await this.repositoryIdentity(root, context);
+            return;
+        }
         const worktree = record(workspace.worktree, "Herdr current workspace worktree");
         const checkout = await realpath(exactString(worktree.checkout_path, "Herdr current checkout_path"));
         if (checkout !== root)

package/dist/launch-runtime.d.ts

@@ -16,6 +16,7 @@ export interface LaunchRuntimeOptions {
         request: ExecuteRequest;
         cwd: string;
         root: string;
+        targeted?: boolean;
     }, context: OperationContext): Promise<void>;
     inspectMainBase(input: {
         root: string;
@@ -44,6 +45,7 @@ export declare class RoleLaunchRuntime implements CoordinatorRuntime {
         request: ExecuteRequest;
         cwd: string;
         dryRun?: boolean;
+        targeted?: boolean;
     }, context: OperationContext): Promise<{
         root: string;
         main: WorkspaceIdentity;

package/dist/launch-runtime.js

@@ -140,12 +140,15 @@ export class RoleLaunchRuntime {
         const root = await realpath(resolvedRoot);
         if (root !== resolvedRoot)
             throw new Error("Pi Subagent root resolver returned a non-canonical path.");
+        // A Repository target must still be its own Git top-level directory before the host gate runs.
+        if (input.targeted && root !== await realpath(input.cwd))
+            throw new Error(`Repository target ${input.cwd} now resolves to ${root}; nothing was saved. Retry the request.`);
         const rootInfo = await lstat(root);
         if (!rootInfo.isDirectory())
             throw new Error("Pi Subagent root must be an existing local directory.");
         context.signal?.throwIfAborted();
         if (!input.dryRun && input.request.tasks.some((task) => task.kind === "changeset")) {
-            await this.options.preflightHost?.({ request: input.request, cwd: input.cwd, root }, context);
+            await this.options.preflightHost?.({ request: input.request, cwd: input.cwd, root, ...(input.targeted ? { targeted: true } : {}) }, context);
         }
         const main = await this.options.inspectMainBase({ root }, context);
         const required = new Map();

package/dist/runner.d.ts

@@ -119,11 +119,15 @@ export declare function withTransientLaunch<Launch extends VerifiedLaunch, Resul
 export interface CoordinatorRuntime {
     now(): number;
     randomToken(): string;
-    /** `dryRun` skips checks that call Herdr; every other check runs. */
+    /**
+     * `dryRun` skips checks that call Herdr; every other check runs.
+     * `targeted` means that `cwd` is a Repository target, so the caller's Herdr workspace can belong to another checkout.
+     */
     preflight(input: {
         request: ExecuteRequest;
         cwd: string;
         dryRun?: boolean;
+        targeted?: boolean;
     }, context: OperationContext): Promise<{
         root: string;
         main: WorkspaceIdentity;
@@ -361,8 +365,13 @@ export declare class IsolatedRunner {
     /** Every execute check before durable state; a dry run also skips the Herdr host preflight. */
     private admitExecute;
     /** Dry run of execute: no state, lock, lease, worktree, or Herdr call. */
-    plan(value: unknown, cwd: string, outerSignal?: AbortSignal): Promise<ExecutePlan>;
-    execute(value: unknown, cwd: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    /** `options.targeted` marks `cwd` as a Repository target that the caller selected with `repo`. */
+    plan(value: unknown, cwd: string, outerSignal?: AbortSignal, options?: {
+        targeted?: boolean;
+    }): Promise<ExecutePlan>;
+    execute(value: unknown, cwd: string, outerSignal?: AbortSignal, options?: {
+        targeted?: boolean;
+    }): Promise<RunResponse>;
     resume(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
     /** Main selects an exact retained candidate; only the owned integration checkout is writable. */
     stage(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
@@ -386,6 +395,20 @@ export declare class IsolatedRunner {
             tasks: never[];
         }[];
     }>;
+    /** Orphaned requests of every primary checkout in one state scan, each with the primary checkout that owns it. */
+    listAllOrphanRequests(): Promise<{
+        invalidIds: string[];
+        requests: {
+            id: string;
+            name: string;
+            status: string;
+            directory: string;
+            root: string;
+            orphaned: true;
+            tasks: never[];
+            primary: string;
+        }[];
+    }>;
     private discardGuards;
     discardPlan(cwd: string, id: string, directory: string | undefined, guards: DiscardGuards): Promise<DiscardPlan>;
     /** Command-only explicit discard. No tool calls this method. */

package/dist/runner.js

@@ -814,14 +814,19 @@ export class IsolatedRunner {
             throw error;
     }
     /** Every execute check before durable state; a dry run also skips the Herdr host preflight. */
-    async admitExecute(value, cwd, scope, dryRun) {
+    async admitExecute(value, cwd, scope, dryRun, targeted) {
         const request = parseExecuteRequest(value);
         const policy = Object.freeze({ ...this.currentPolicy() });
         const canonicalCwd = realpathSync.native(cwd);
-        const prepared = await scope.call(async (context) => await this.coordinatorRuntime.preflight({ request, cwd: canonicalCwd, ...(dryRun ? { dryRun } : {}) }, context));
+        const prepared = await scope.call(async (context) => await this.coordinatorRuntime.preflight({
+            request, cwd: canonicalCwd, ...(dryRun ? { dryRun } : {}), ...(targeted ? { targeted } : {}),
+        }, context));
         const root = realpathSync.native(prepared.root);
         if (root !== prepared.root)
             throw new Error("Preflight repository root must be canonical.");
+        // A Repository target is its own root. A different root means the checkout changed after the target check.
+        if (targeted && root !== canonicalCwd)
+            throw new Error(`Repository target ${canonicalCwd} now resolves to ${root}; nothing was saved. Retry the request.`);
         let fullSuite;
         if (request.tasks.some((task) => task.kind === "changeset")) {
             // Main is clean and committed here, so the working files are the committed sources.
@@ -844,13 +849,14 @@ export class IsolatedRunner {
         return { request, policy, root, preparedMain, routes: prepared.routes ?? [], ...(fullSuite ? { fullSuite } : {}) };
     }
     /** Dry run of execute: no state, lock, lease, worktree, or Herdr call. */
-    async plan(value, cwd, outerSignal) {
-        const { request, root, preparedMain, routes, fullSuite } = await this.admitExecute(value, cwd, new ProductiveScope(outerSignal), true);
+    /** `options.targeted` marks `cwd` as a Repository target that the caller selected with `repo`. */
+    async plan(value, cwd, outerSignal, options = {}) {
+        const { request, root, preparedMain, routes, fullSuite } = await this.admitExecute(value, cwd, new ProductiveScope(outerSignal), true, options.targeted === true);
         return { request, root, main: preparedMain, routes, ...(fullSuite ? { fullSuite } : {}) };
     }
-    async execute(value, cwd, outerSignal) {
+    async execute(value, cwd, outerSignal, options = {}) {
         const scope = new ProductiveScope(outerSignal);
-        const { request, policy, root, preparedMain, fullSuite } = await this.admitExecute(value, cwd, scope, false);
+        const { request, policy, root, preparedMain, fullSuite } = await this.admitExecute(value, cwd, scope, false, options.targeted === true);
         return await this.withProductiveRun(root, async (lifecycle) => {
             const createdAt = this.coordinatorRuntime.now();
             const state = {
@@ -1788,6 +1794,14 @@ export class IsolatedRunner {
                 directory: dirname(handle.path), root: handle.state.root, orphaned: true, tasks: [],
             })) };
     }
+    /** Orphaned requests of every primary checkout in one state scan, each with the primary checkout that owns it. */
+    async listAllOrphanRequests() {
+        const { states, invalidIds, primaries } = await this.store.listOrphans();
+        return { invalidIds, requests: states.map((handle) => ({
+                id: handle.state.request.id, name: handle.state.request.goal, status: inventoryStatus(handle.state, true),
+                directory: dirname(handle.path), root: handle.state.root, orphaned: true, tasks: [], primary: primaries.get(handle),
+            })) };
+    }
     discardGuards(directory, root, guards) {
         return { ...guards, blocked: async () => {
                 if (this.productiveLifecycles.has(root))

package/dist/store.d.ts

@@ -47,11 +47,19 @@ export declare class FileRunStore {
     private loadFromValidatedDirectory;
     hasProductiveRunLeaseInDirectory(directory: string): Promise<boolean>;
     withDirectoryLock<T>(directory: string, operation: () => Promise<T>): Promise<T>;
-    /** Missing roots only; repoRoot records the stable primary checkout, not the removed parent. */
+    /**
+     * Missing roots only; repoRoot records the stable primary checkout, not the removed parent.
+     * Without `primary`, return the orphans of every primary checkout, each with its primary.
+     */
     listOrphans(primary: string): Promise<{
         states: RunStateHandle[];
         invalidIds: string[];
     }>;
+    listOrphans(primary?: undefined): Promise<{
+        states: RunStateHandle[];
+        invalidIds: string[];
+        primaries: Map<RunStateHandle, string>;
+    }>;
     private stateEntries;
     /** Read only version and request status; never migrate or interpret v4 or v5 worker evidence. */
     assertLegacyAdmissionSafe(root: string): Promise<void>;

package/dist/store.js

@@ -255,8 +255,8 @@ export class FileRunStore {
             await release();
         }
     }
-    /** Missing roots only; repoRoot records the stable primary checkout, not the removed parent. */
     async listOrphans(primary) {
+        const primaries = new Map();
         const parent = join(extensionConfigDir("pi-subagent", this.agentDir), "state");
         let directories;
         try {
@@ -264,7 +264,7 @@ export class FileRunStore {
         }
         catch (error) {
             if (isMissing(error))
-                return { states: [], invalidIds: [] };
+                return { states: [], invalidIds: [], ...(primary === undefined ? { primaries } : {}) };
             throw error;
         }
         const states = [];
@@ -291,7 +291,14 @@ export class FileRunStore {
                                 throw error;
                         }
                         const worktrees = discardResources(handle.state).flatMap((resource) => resource.worktree ? [resource.worktree] : []);
-                        if (worktrees.length && worktrees.every((item) => item.repoRoot === primary))
+                        const owner = worktrees[0]?.repoRoot;
+                        if (owner === undefined || !worktrees.every((item) => item.repoRoot === owner))
+                            continue;
+                        if (primary === undefined) {
+                            primaries.set(handle, owner);
+                            states.push(handle);
+                        }
+                        else if (owner === primary)
                             states.push(handle);
                     }
                     catch {
@@ -305,7 +312,7 @@ export class FileRunStore {
                 invalidIds.push(directory);
             }
         }
-        return { states, invalidIds };
+        return { states, invalidIds, ...(primary === undefined ? { primaries } : {}) };
     }
     async stateEntries(root) {
         try {

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,
@@ -43,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;
@@ -87,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 {
@@ -522,10 +525,32 @@ export function formatExecutePlan(plan: ExecutePlan, hostChecked: boolean): { co
 	};
 }
 
+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>;
@@ -587,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) => {
@@ -756,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)}` }];
@@ -773,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),
@@ -789,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);
 		},
 	});
@@ -802,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) => {
@@ -830,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) {
@@ -858,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,
@@ -937,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

@@ -703,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 };
@@ -716,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": "28.0.0",
+  "version": "28.1.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",