@hcflabs/pi-subagent 27.10.8 → 28.0.0

package/dist/schema.js

@@ -2,7 +2,7 @@ import { isAbsolute } from "node:path";
 import { parseRoleName } from "./index.js";
 import { Type } from "typebox";
 import { Check, Errors } from "typebox/value";
-export const RUN_STATE_VERSION = 5;
+export const RUN_STATE_VERSION = 6;
 export const MAX_TASKS = 8;
 export const MAX_EXECUTE_REQUEST_BYTES = 256 * 1024;
 export const MAX_PERSISTED_RUNTIME_TEXT_BYTES = 8 * 1024;
@@ -26,6 +26,19 @@ export const CheckCommandSchema = Type.Object({
     command: TextSchema,
     args: Type.Array(Type.String({ maxLength: 16_000 }), { maxItems: 128 }),
 }, { additionalProperties: false });
+/** The Full suite fixed at admission, with its source. Validation checks the same source again. */
+export const FullSuiteSchema = Type.Object({
+    check: CheckCommandSchema,
+    source: Type.Union([
+        Type.Object({ kind: Type.Literal("config") }, { additionalProperties: false }),
+        Type.Object({ kind: Type.Literal("package-json"), testScript: Type.String({ minLength: 1, maxLength: 16_000 }) }, { additionalProperties: false }),
+        Type.Object({
+            kind: Type.Literal("makefile"),
+            file: Type.Union([Type.Literal("GNUmakefile"), Type.Literal("makefile"), Type.Literal("Makefile")]),
+            sha256: Type.String({ pattern: "^[0-9a-f]{64}$" }),
+        }, { additionalProperties: false }),
+    ]),
+}, { additionalProperties: false });
 /** One display form for a check command; quoted args keep argv boundaries visible. */
 export function formatCheckCommand({ command, args }) {
     return [command, ...args.map((arg) => JSON.stringify(arg))].join(" ");
@@ -420,6 +433,8 @@ const RunStateSchema = Type.Object({
     version: Type.Literal(RUN_STATE_VERSION),
     request: ExecuteRequestSchema,
     policy: ExecutionPolicySnapshotSchema,
+    /** Present exactly when the request has a changeset task. */
+    fullSuite: Type.Optional(FullSuiteSchema),
     correctionCount: Type.Integer({ minimum: 0 }),
     root: TextSchema,
     requestStartMain: WorkspaceSchema,
@@ -1015,6 +1030,13 @@ export function parseRunState(value) {
     const state = value;
     const request = parseExecuteRequest(state.request);
     parseIntegrationState(state.integration, request);
+    const changeset = request.tasks.some((task) => task.kind === "changeset");
+    if (changeset !== (state.fullSuite !== undefined))
+        throw new Error("A Full suite must be recorded exactly for a request with changeset tasks.");
+    if (state.fullSuite && !request.finalChecks.some(({ command, args }) => command === state.fullSuite.check.command
+        && args.length === state.fullSuite.check.args.length && args.every((arg, index) => arg === state.fullSuite.check.args[index]))) {
+        throw new Error("The recorded Full suite is not in the request final checks.");
+    }
     if (state.status !== "aborted" && state.integration.generations.some((generation) => generation.supersededFrom === "discarded")) {
         throw new Error("User-discarded generations require an aborted request.");
     }

package/dist/store.d.ts

@@ -53,7 +53,7 @@ export declare class FileRunStore {
         invalidIds: string[];
     }>;
     private stateEntries;
-    /** Read only version and request status; never migrate or interpret v4 worker evidence. */
+    /** Read only version and request status; never migrate or interpret v4 or v5 worker evidence. */
     assertLegacyAdmissionSafe(root: string): Promise<void>;
     list(root: string): Promise<{
         states: RunStateHandle[];

package/dist/store.js

@@ -18,8 +18,10 @@ const INITIAL_STATE_MAX_BYTES = 2 * 1024 * 1024;
 const STATE_MAX_BYTES = 128 * 1024 * 1024;
 const ADMISSION_MAX_FILES = 256;
 const ADMISSION_MAX_BYTES = STATE_MAX_BYTES;
-const V4_TERMINAL_STATUSES = new Set(["completed", "final_failed", "superseded", "aborted"]);
-const V4_UNFINISHED_STATUSES = new Set(["pending", "running", "needs_attention"]);
+// v4 and v5 use the same request statuses. Admission reads only the version and the status of older files.
+const LEGACY_VERSIONS = new Set([4, 5]);
+const LEGACY_TERMINAL_STATUSES = new Set(["completed", "final_failed", "superseded", "aborted"]);
+const LEGACY_UNFINISHED_STATUSES = new Set(["pending", "running", "needs_attention"]);
 const LOCK_OPTIONS = { realpath: false, stale: 30_000, update: 5_000, retries: 0 };
 const LIFECYCLE_LOCK_OPTIONS = {
     ...LOCK_OPTIONS,
@@ -317,7 +319,7 @@ export class FileRunStore {
             throw error;
         }
     }
-    /** Read only version and request status; never migrate or interpret v4 worker evidence. */
+    /** Read only version and request status; never migrate or interpret v4 or v5 worker evidence. */
     async assertLegacyAdmissionSafe(root) {
         const directory = this.stateDirectory(root);
         await this.assertSafeDestination(root, directory);
@@ -348,12 +350,12 @@ export class FileRunStore {
             }
             if (value.version === RUN_STATE_VERSION)
                 continue;
-            if (value.version !== 4 || !("status" in value) || typeof value.status !== "string"
-                || (!V4_TERMINAL_STATUSES.has(value.status) && !V4_UNFINISHED_STATUSES.has(value.status))) {
+            if (typeof value.version !== "number" || !LEGACY_VERSIONS.has(value.version) || !("status" in value) || typeof value.status !== "string"
+                || (!LEGACY_TERMINAL_STATUSES.has(value.status) && !LEGACY_UNFINISHED_STATUSES.has(value.status))) {
                 throw new Error(`Pi Subagent malformed or unsupported legacy state ${id} blocks safe admission. ${recovery}`);
             }
-            if (V4_UNFINISHED_STATUSES.has(value.status)) {
-                throw new Error(`Pi Subagent unfinished v4 request ${id} (${value.status}) blocks new isolated work. ${recovery}`);
+            if (LEGACY_UNFINISHED_STATUSES.has(value.status)) {
+                throw new Error(`Pi Subagent unfinished v${value.version} request ${id} (${value.status}) blocks new isolated work. ${recovery}`);
             }
         }
     }

package/docs/orchestration.md

@@ -81,7 +81,7 @@ Direct `changeset` is rejected; use isolated mode for checked integration. Resou
 
 ### Dry run
 
-Set `"dryRun": true` on a direct or isolated `delegate_task` request to check it without a launch. The dry run does the same checks as a launch: request shape, Role lookup, route and model with thinking level, Skills, tools, MCP allowlist, Role extensions, config, and `continueFrom` eligibility. For an isolated request, it also checks the task graph and that Main is clean and committed. If the request has a changeset task, it also checks the canonical root `package.json` test script and adds `pnpm test` to the final checks. A failed check gives the same error as a launch.
+Set `"dryRun": true` on a direct or isolated `delegate_task` request to check it without a launch. The dry run does the same checks as a launch: request shape, Role lookup, route and model with thinking level, Skills, tools, MCP allowlist, Role extensions, config, and `continueFrom` eligibility. For an isolated request, it also checks the task graph and that Main is clean and committed. If the request has a changeset task, it also selects the Full suite, adds it to the final checks, and shows it. A failed check gives the same error as a launch.
 
 The result is a bounded plan. It shows each task's Role, resolved `provider/model`, thinking level, access or kind, dependencies, and checks. An isolated plan also shows the final checks. The dry run makes no Herdr call, Herdr tab, session record, saved state, worktree, lease, checkout admission, or follow-up. The plan lists each check it cannot do without such an effect as `Not checked: <reason>`. Examples are the Herdr host preflight, checkout admission, and the stop of a continued agent.
 
@@ -93,6 +93,8 @@ For example, a configured Git operator with `bash` can stage named pending files
 
 Direct writes change Main's checkout immediately. They require no clean checkout. They give no automatic checks, rollback, or isolated integration guarantee. A write request cannot start while a direct writer owns the checkout. It also cannot start while a Main call that can write is in progress there.
 
+A task with `repo` runs in that Repository target instead of Main's checkout. Admission resolves the target before the launch and reserves the checkout of each target at one time. Two checkouts conflict when one contains the other. Thus a Main call from a non-Git parent directory covers the checkout of every Repository target in it, and writers in two different Repository targets can run together. An invalid `repo` blocks the call before any reservation. Admission does not parse Bash text for a directory.
+
 A write request runs its tasks in sequence. It holds checkout admission after the initial handle returns. Competing direct writers and Main writes fail until the extension proves that all owned workers stopped. To keep Main free to write, use `mode: isolated`. This mode gives worktree checks and explicit integration, not immediate changes to the shared checkout. Parallel read requests still run concurrently.
 
 A failure in a write request stops further dispatch, but a worker with an uncertain state can still run. Chains replace each literal `{previous}` with the preceding successful answer and stop on failure. Task outcome and worker termination are separate.
@@ -255,7 +257,7 @@ Every task declares `id`, `kind`, `role`, `modelClass`, `requirements`, `deliver
 - A `changeset` task requires focused checks and owns one worktree, Herdr workspace, worker tab, and retained worker.
 - `dependsOn` controls ready waves; dependent tasks can run from a selected staged snapshot only after Main explicitly advances it.
 - `contextFrom` may reference completed text tasks only, implies scheduling dependencies, and preserves declaration order. It must not overlap `dependsOn`.
-- A graph containing changesets requires final checks. The repository root must have a `package.json` test script; admission prepends canonical `pnpm test` if absent from final checks. Combined validation rejects a changed root test script.
+- A graph containing changesets requires final checks. Admission selects one Full suite: the `repoSuites` config entry, then `pnpm test` for a root `package.json` test script, then `make test` for a literal Makefile `test` target. It prepends the suite to the final checks if absent and saves the suite with its source in state v6. Combined validation rejects a changed root test script or Makefile. A config change after admission does not change the saved suite.
 
 Admission and worker-wave dispatch pin Main's exact committed branch, HEAD, and tree without inspecting or modifying its staged, unstaged, or untracked edits. Worker allocation verifies the same committed identity around worktree creation, including resumed waves; staged-dependent waves verify their clean integration snapshot. A dirty Main can therefore produce a checked retained candidate, but branch/HEAD drift stops new waves. The runner executes ready worker tasks concurrently, inspects clean committed candidates, runs preliminary task checks and optional preliminary judgment, then records ready candidates for Main. **It does not automatically integrate them.**
 

package/extensions/admission.ts

@@ -1,12 +1,20 @@
 import { realpath } from "node:fs/promises";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isWithin, resolveRepoTarget } from "@hcflabs/pi-repo";
 
 // Main's own tools that never change a checkout; every other Main call may write.
 // `codemode` mutates nothing itself: its nested tool calls are admitted by their own names.
 const MAIN_NON_WRITING_TOOLS = new Set([
-	"read", "grep", "find", "ffgrep", "fffind", "ls", "codegraph_explore", "subagent_status", "codemode",
+	"read", "grep", "find", "ffgrep", "fffind", "ls", "codegraph_explore", "subagent_status", "subagent_repos", "codemode",
 ]);
 
+/**
+ * Classification of a `delegate_task` call. `false` means the call does not write.
+ * `true` means a writer in the Pi working directory. A list names the Repository target of each task.
+ * `undefined` in the list means the Pi working directory.
+ */
+export type DirectAdmission = boolean | ReadonlyArray<string | undefined>;
+
 async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<string> {
 	const cwd = await realpath(ctx.cwd);
 	const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd, timeout: 5_000 });
@@ -16,15 +24,23 @@ async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<str
 	return await realpath(root);
 }
 
+/** Two scopes conflict when one contains the other. A non-Git parent directory covers its whole subtree. */
+const overlaps = (left: string, right: string) => isWithin(left, right) || isWithin(right, left);
+
 /**
  * Reserve checkouts only for direct writers. Main writes can run together, but
- * each call must finish before a direct writer can start in that checkout.
+ * each call must finish before a direct writer can start in an overlapping checkout.
+ * A direct writer reserves the checkout of each task target at one time.
  * External processes and trusted extension lifecycle code are not intercepted.
  */
-export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (input: unknown) => boolean): (toolCallId: string) => () => void {
+export type CheckoutAdmission = ((toolCallId: string) => () => void) & {
+	/** The real checkout paths that admission reserved for a direct writer call. */
+	admitted(toolCallId: string): readonly string[] | undefined;
+};
+
+export function registerCheckoutAdmission(pi: ExtensionAPI, classifyDirect: (input: unknown) => DirectAdmission): CheckoutAdmission {
 	const heldCalls = new Set<string>();
-	const ownerByCheckout = new Map<string, string>();
-	const calls = new Map<string, { direct: boolean; key?: string }>();
+	const calls = new Map<string, { direct: boolean; keys?: readonly string[] }>();
 	// One Git lookup per working directory per session; a failed lookup is retried.
 	const checkouts = new Map<string, Promise<string>>();
 	const lookup = (ctx: ExtensionContext) => {
@@ -35,32 +51,49 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (inp
 		key.catch(() => { if (checkouts.get(ctx.cwd) === key) checkouts.delete(ctx.cwd); });
 		return key;
 	};
+	const targetKey = async (ctx: ExtensionContext, repo: string | undefined) => {
+		if (repo === undefined) return await lookup(ctx);
+		const target = await resolveRepoTarget(ctx.cwd, repo, {
+			runProcess: (command, args, options) => pi.exec(command, args, { cwd: options.cwd, timeout: options.timeoutMs ?? undefined, ...(options.signal ? { signal: options.signal } : {}) }),
+		});
+		return target.root;
+	};
 	const release = (toolCallId: string) => {
 		if (heldCalls.has(toolCallId)) return;
-		const call = calls.get(toolCallId);
 		calls.delete(toolCallId);
-		if (call?.key && ownerByCheckout.get(call.key) === toolCallId) ownerByCheckout.delete(call.key);
 	};
 	pi.on("tool_call", async (event, ctx) => {
 		const direct = event.toolName === "delegate_task";
-		if (direct ? !directCanWrite(event.input) : MAIN_NON_WRITING_TOOLS.has(event.toolName)) return;
-		const call: { direct: boolean; key?: string } = { direct };
+		const classified = direct ? classifyDirect(event.input) : !MAIN_NON_WRITING_TOOLS.has(event.toolName);
+		if (classified === false) return;
+		const repos: ReadonlyArray<string | undefined> = classified === true ? [undefined] : classified;
+		const call: { direct: boolean; keys?: readonly string[] } = { direct };
 		calls.set(event.toolCallId, call);
-		const key = await lookup(ctx);
+		let keys: string[];
+		try {
+			keys = [...new Set(await Promise.all(repos.map((repo) => targetKey(ctx, repo))))];
+		} catch (error) {
+			release(event.toolCallId);
+			if (!direct || repos.every((repo) => repo === undefined)) throw error;
+			return { block: true, reason: `Repository target check failed: ${error instanceof Error ? error.message : String(error)}` };
+		}
 		if (calls.get(event.toolCallId) !== call) {
 			return { block: true, reason: `Call ${event.toolCallId} already settled; use mode: isolated to keep Main free.` };
 		}
-		const owner = ownerByCheckout.get(key);
-		const main = direct ? [...calls].find(([, active]) => !active.direct && active.key === key)?.[0] : undefined;
-		if (owner || main) {
+		// A direct writer conflicts with every overlapping call. A Main call conflicts only with a direct writer.
+		const conflict = [...calls].find(([id, active]) => id !== event.toolCallId && active.keys
+			&& (direct || active.direct)
+			&& active.keys.some((held) => keys.some((key) => overlaps(held, key))));
+		if (conflict) {
+			const [owner, active] = conflict;
+			const key = active.keys!.find((held) => keys.some((candidate) => overlaps(held, candidate)))!;
 			release(event.toolCallId);
 			return {
 				block: true,
-				reason: `Checkout ${key} has ${owner ? `an admitted direct writer (${owner})` : `a Main potentially-writing call in flight (${main})`}; retry after it stops, or use mode: isolated to keep Main free.`,
+				reason: `Checkout ${key} has ${active.direct ? `an admitted direct writer (${owner})` : `a Main potentially-writing call in flight (${owner})`}; retry after it stops, or use mode: isolated to keep Main free.`,
 			};
 		}
-		call.key = key;
-		if (direct) ownerByCheckout.set(key, event.toolCallId);
+		call.keys = keys;
 	});
 	pi.on("tool_result", (event) => release(event.toolCallId));
 	pi.on("tool_execution_end", (event) => release(event.toolCallId));
@@ -71,12 +104,18 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (inp
 		for (const toolCallId of calls.keys()) release(toolCallId);
 	});
 	// The tool returns a handle before its worker stops. Release only after verified termination.
-	return (toolCallId) => {
+	const hold = (toolCallId: string) => {
 		const call = calls.get(toolCallId);
-		if (!call?.direct || !call.key) {
+		if (!call?.direct || !call.keys) {
 			throw new Error(`Direct call ${toolCallId} was not admitted as a checkout writer; delegate again.`);
 		}
 		heldCalls.add(toolCallId);
 		return () => { heldCalls.delete(toolCallId); release(toolCallId); };
 	};
+	return Object.assign(hold, {
+		admitted: (toolCallId: string) => {
+			const call = calls.get(toolCallId);
+			return call?.direct ? call.keys : undefined;
+		},
+	});
 }

package/extensions/isolated.ts

@@ -16,6 +16,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 +30,7 @@ import {
 	sameIdentity,
 	StatusOutputSchema,
 	type CheckBatchEvidence,
+	type CheckCommand,
 	type ExecuteRequest,
 	type ExecutionPolicySnapshot,
 	type ModelClass,
@@ -61,12 +63,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 })
@@ -96,6 +100,8 @@ export const createIsolatedComponents: CreateIsolatedComponents = ({
 			executor,
 			policy,
 			currentPolicy,
+			undefined,
+			repoSuites,
 		),
 	};
 };
@@ -473,7 +479,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 +502,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,6 +515,7 @@ 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,
 		},
@@ -533,6 +542,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 +577,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);

package/extensions/repos.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { discoverRepos } from "@hcflabs/pi-repo";
+import { Type } from "typebox";
+
+const OUTPUT_REPOS = 200;
+
+const Parameters = Type.Object({
+	path: Type.Optional(Type.String({ minLength: 1, description: "Directory to search, relative to the Pi working directory. The default is the Pi working directory." })),
+	maxDepth: Type.Optional(Type.Integer({ minimum: 1, maximum: 8, description: "Directory levels to search below path. The default is 3." })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: OUTPUT_REPOS, description: `Maximum repositories to return. The default is ${OUTPUT_REPOS}.` })),
+}, { additionalProperties: false });
+
+/** Register the read-only `subagent_repos` tool. It lists child repositories and the `repo` selector for each. */
+export function registerRepoDiscovery(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "subagent_repos",
+		label: "Subagent Repos",
+		description: "List the child Git repositories below the Pi working directory, with the repo selector that delegate_task accepts. The tool changes no files and no Git state. It does not follow symlinks and does not search inside a repository.",
+		promptSnippet: "List child Git repositories and their repo selectors for delegate_task",
+		promptGuidelines: [
+			"When the Pi working directory holds several repositories, use subagent_repos to find the repo selector, then set repo on delegate_task. Never guess a selector, and never select a repository the user did not name or authorize.",
+		],
+		parameters: Parameters,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const found = await discoverRepos(ctx.cwd, {
+				...(params.path === undefined ? {} : { path: params.path }),
+				...(params.maxDepth === undefined ? {} : { maxDepth: params.maxDepth }),
+				limit: params.limit ?? OUTPUT_REPOS,
+				...(signal ? { signal } : {}),
+			});
+			const lines = [
+				`${found.repos.length} repositories below ${found.base}${found.truncated ? " (truncated: a limit stopped the search)" : ""}.`,
+				...found.repos.map(({ repo, linkedWorktree }) => `${repo}${linkedWorktree ? " (linked worktree)" : ""}`),
+				...(found.issues.length ? ["Issues:", ...found.issues.slice(0, 20).map(({ path, reason }) => `${path}: ${reason}`)] : []),
+				...(found.issues.length > 20 ? [`${found.issues.length - 20} more issues omitted.`] : []),
+			];
+			return { content: [{ type: "text" as const, text: lines.join("\n") }], details: found };
+		},
+	});
+}

package/extensions/subagent.ts

@@ -3,14 +3,16 @@ import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-c
 import { type Component, Text, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { availableTaskModels, loadTaskModelsConfig, modelReference, type ProfileName, registerModelTask, registerTaskModelsConfigReporting, resolveAvailableModel, resolveConfiguredTaskRoute, type ResolvedTaskRoute, taskThinkingLevels } from "@hcflabs/pi-task-models";
 import { registerConfigReporting } from "@hcflabs/pi-config-store";
+import { resolveRepoTarget } from "@hcflabs/pi-repo";
 import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, createSubagentConfigStore, DEFAULT_SUBAGENT_CONFIG, DELEGATE_TASK, findRole, formatDuration, loadRoleCatalog, prepareRoleLaunch, resolveRolePackageResources, resolveTaskRoute, ROLE_TOOL_POLICY_FLAG, type ExecutionPolicySnapshot, type Role } from "@hcflabs/pi-subagent";
 import { resolveExecutionPolicy } from "./config.ts";
 import { registerCheckoutAdmission } from "./admission.ts";
 import { registerIsolatedExtension } from "./isolated.ts";
+import { registerRepoDiscovery } from "./repos.ts";
 import { directRef, registerSubagentCommand, type DirectDisplay, type DirectTask } from "./subagent-command.ts";
 import { MODEL_CLASS_GUIDANCE } from "./model-class-policy.ts";
 import { compactCost, compactTokens, ENTRY_STATUS_PRESENTATION, formatWorkflowResult, workerOutputForMain, type BackgroundWorkflowTransportDetails, type WorkflowTransportEntry } from "./result-transport.ts";
-import { checkoutNote, DelegateTaskParameters, identifyWorkflowEntries, parseDelegateTask, runForegroundWorkflow, snapshotCheckout, writesCheckout, type CheckoutSnapshot, type ParsedWorkflow, type WorkflowEntry } from "./workflow.ts";
+import { checkoutNote, DelegateTaskParameters, identifyWorkflowEntries, parseDelegateTask, runForegroundWorkflow, snapshotCheckout, workflowRepos, writesCheckout, type CheckoutSnapshot, type ParsedWorkflow, type WorkflowEntry } from "./workflow.ts";
 import { assertSettledDirectSession, createDirectHerdr, DirectAllocationError, directTaskReader, type DirectAllocation, type DirectHandle, type DirectTab, type DirectToolActivity, type DirectUsage } from "../dist/direct-herdr.js";
 import { materializeTransientLaunch } from "../dist/launch-runtime.js";
 const WIDGET_KEY = "subagent-status";
@@ -223,15 +225,17 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		reportConfig(ctx);
 		currentPolicy();
 	};
-	const canWrite = (input: unknown): boolean => {
+	/** A direct writer reserves the checkout of each task target. An unparsable call is a writer in the Pi working directory. */
+	const classifyDirect = (input: unknown): boolean | Array<string | undefined> => {
 		try {
 			const parsed = parseDelegateTask(input);
-			return parsed.mode === "direct" && !parsed.dryRun && writesCheckout(parsed.workflow);
+			return parsed.mode === "direct" && !parsed.dryRun && writesCheckout(parsed.workflow) && workflowRepos(parsed.workflow);
 		} catch {
 			return true;
 		}
 	};
-	const holdAdmission = registerCheckoutAdmission(pi, canWrite);
+	const holdAdmission = registerCheckoutAdmission(pi, classifyDirect);
+	registerRepoDiscovery(pi);
 	/** Resolve a Role's package resources and route for a direct Herdr launch. */
 	const prepareDirectLaunch = async (role: Role, context: ExtensionContext, options: { modelClass?: ProfileName; model?: string }) => {
 		const resources = await resolveRolePackageResources(role, context);
@@ -251,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;
@@ -634,7 +640,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	};
 
 	/** Dry run of a direct launch: the same checks, then a bounded plan; no tab, record, admission, or follow-up. */
-	const planDirect = async (workflow: ParsedWorkflow, sources: ReadonlyMap<number, DirectTabRecord & { turn: string }>, cwd: string, ctx: ExtensionContext) => {
+	const planDirect = async (workflow: ParsedWorkflow, sources: ReadonlyMap<number, DirectTabRecord & { turn: string }>, cwd: string, targets: readonly string[], ctx: ExtensionContext) => {
 		for (const [index, source] of sources) {
 			try { await assertSettledDirectSession(source.sessionFile, source.turn); } catch (error) {
 				throw boundedError(new Error(`Cannot continue ${workflow.delegations[index]!.continueFrom}: ${error instanceof Error ? error.message : String(error)}.`, { cause: error }));
@@ -652,6 +658,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				directTaskReader(workflow.mode === "chain" ? delegation.task.replaceAll("{previous}", "") : delegation.task, prepared.tools);
 			} catch (error) { throw boundedError(error); }
 			entries.push({ index, name, role, access, model: modelReference(prepared.model), thinkingLevel: prepared.thinkingLevel,
+				...(delegation.repo === undefined ? {} : { repo: delegation.repo, cwd: targets[index]! }),
 				...(continueFrom === undefined ? {} : { continueFrom }), ...(workflow.mode === "chain" && index ? { after: index } : {}) });
 		}
 		const writes = writesCheckout(workflow);
@@ -663,8 +670,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		];
 		const text = [
 			`Dry run passed: direct ${workflow.mode} request with ${entries.length} task(s) in ${cwd}. No Herdr tab, session record, checkout admission, or follow-up was created.`,
-			...entries.map((entry) => `${entry.index + 1}. ${entry.name} · ${entry.role} · ${entry.model} · thinking ${entry.thinkingLevel} · access ${entry.access}${entry.access === "write" ? " (JSON completion required)" : ""}${entry.after ? ` · after ${entry.after}` : ""}${entry.continueFrom ? ` · continues ${entry.continueFrom}` : ""}`),
-			writes ? "Write request: tasks would run serially and reserve this checkout until owned workers are proved stopped."
+			...entries.map((entry) => `${entry.index + 1}. ${entry.name} · ${entry.role} · ${entry.model} · thinking ${entry.thinkingLevel} · access ${entry.access}${entry.access === "write" ? " (JSON completion required)" : ""}${entry.repo ? ` · repo ${entry.repo} (${entry.cwd})` : ""}${entry.after ? ` · after ${entry.after}` : ""}${entry.continueFrom ? ` · continues ${entry.continueFrom}` : ""}`),
+			writes ? `Write request: tasks would run serially and reserve ${new Set(targets).size > 1 ? "each target checkout" : "this checkout"} until owned workers are proved stopped.`
 				: "Read request: tasks would run concurrently without checkout admission.",
 			...notChecked.map((reason) => `Not checked: ${reason}.`),
 		].join("\n");
@@ -720,7 +727,25 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			const branchTabs = ctx.sessionManager.getBranch().flatMap((entry) =>
 				entry.type === "custom" && entry.customType === DIRECT_TAB_TYPE && entry.data ? [entry.data as DirectTabRecord] : []);
 			const policy = currentPolicy();
-			const herdr = createDirectHerdr(pi, ctx.cwd, policy.childIdleMs);
+			// Resolve each Repository target before continuation checks, admission evidence, or Herdr calls.
+			const targets: string[] = [];
+			for (const [index, { repo }] of workflow.delegations.entries()) {
+				if (repo === undefined) { targets.push(ctx.cwd); continue; }
+				try {
+					targets.push((await resolveRepoTarget(ctx.cwd, repo, signal ? { signal } : {})).root);
+				} catch (error) {
+					throw boundedError(new Error(`Task ${index + 1} repo ${repo}: ${error instanceof Error ? error.message : String(error)}`, { cause: error }));
+				}
+			}
+			// Workers open in the caller's Herdr workspace with the target as their working directory.
+			const herdrByCwd = new Map<string, ReturnType<typeof createDirectHerdr>>();
+			const herdrFor = (cwd: string) => {
+				let client = herdrByCwd.get(cwd);
+				if (!client) herdrByCwd.set(cwd, client = createDirectHerdr(pi, cwd, policy.childIdleMs));
+				return client;
+			};
+			const herdr = herdrFor(ctx.cwd);
+			const entryCwd = (index: number) => herdrFor(targets[index]!).cwd;
 			const sources = new Map<number, DirectTabRecord & { turn: string }>();
 			for (const [index, { continueFrom, role }] of workflow.delegations.entries()) {
 				if (continueFrom === undefined) continue;
@@ -731,27 +756,28 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				const source = matches[0]!;
 				if (source.display!.role !== role) throw refuse(`it ran with Role ${source.display!.role}, not ${role}; use the recorded Role`);
 				if (source.turn === undefined) throw refuse("its record has no turn identity (saved by an older pi-subagent), so it is not continuable; start a fresh task");
-				if (source.workspaceId !== herdr.workspaceId || source.cwd !== herdr.cwd) {
-					throw refuse(`it ran in ${source.cwd ?? "an unrecorded checkout"} (Herdr workspace ${source.workspaceId ?? "unrecorded"}), not this checkout and workspace; start a fresh task here`);
+				const target = herdrFor(targets[index]!);
+				if (source.workspaceId !== target.workspaceId || source.cwd !== target.cwd) {
+					throw refuse(`it ran in ${source.cwd ?? "an unrecorded checkout"} (Herdr workspace ${source.workspaceId ?? "unrecorded"}), not in ${target.cwd} and this workspace; select the repo where it ran, or start a fresh task`);
 				}
 				if ([...directTasks.values()].some(({ tabs, continues }) => continues?.has(source.sessionFile)
 					|| tabs.some(({ sessionFile }) => sessionFile === source.sessionFile))) throw refuse("a locally active direct task still owns its session");
 				if ([...sources.values()].some(({ sessionFile }) => sessionFile === source.sessionFile)) throw refuse("this request already continues its session");
 				sources.set(index, { ...source, turn: source.turn });
 			}
-			if (parsed.dryRun) return await planDirect(workflow, sources, herdr.cwd, latestCtx ?? ctx);
+			if (parsed.dryRun) return await planDirect(workflow, sources, herdr.cwd, workflow.delegations.map((_, index) => entryCwd(index)), latestCtx ?? ctx);
 			const writes = writesCheckout(workflow);
 			const entries = identifyWorkflowEntries(toolCallId, workflow);
 			const states = new Map<string, WorkflowTransportEntry>(entries.map(({ id, index, delegation }) => [id, {
 				id, index, role: delegation.role, status: "pending",
-				name: delegation.continueFrom === undefined ? delegation.name : `${delegation.name} (continued from ${delegation.continueFrom})`,
+				name: `${delegation.continueFrom === undefined ? delegation.name : `${delegation.name} (continued from ${delegation.continueFrom})`}${delegation.repo === undefined ? "" : ` · repo ${delegation.repo}`}`,
 			}]));
 			const startedAt = new Map<string, number>();
 			// Launch snapshots: write requests report changes; read requests detect a stale checkout.
 			const snapshots = new Map<string, CheckoutSnapshot | Error | undefined>();
-			const checkout = async ({ id, delegation }: WorkflowEntry) => {
+			const checkout = async ({ id, index, delegation }: WorkflowEntry) => {
 				if (!snapshots.has(id)) return {};
-				const note = await checkoutNote(ctx.cwd, snapshots.get(id), writes, delegation.paths);
+				const note = await checkoutNote(entryCwd(index), snapshots.get(id), writes, delegation.paths);
 				return note ? { checkout: note } : {};
 			};
 			const measured = (id: string, usage: DirectUsage | undefined) => ({
@@ -780,6 +806,16 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			const settled = new Promise<void>((resolve) => { resolveSettled = resolve; });
 			// Register before Herdr can create a tab: session switches must await this
 			// launch, including its identity callback, before copying recovery records.
+			if (writes) {
+				// A selector can point somewhere else after admission resolved it, for example through a symlink.
+				// Launch only in the exact checkouts that admission reserved.
+				const admitted = holdAdmission.admitted(toolCallId) ?? [];
+				for (const [index, { repo }] of workflow.delegations.entries()) {
+					if (repo !== undefined && !admitted.includes(targets[index]!)) {
+						throw boundedError(new Error(`Task ${index + 1} repo ${repo} resolves to ${targets[index]}, which admission did not reserve (${admitted.join(", ") || "none"}). The target changed after admission; delegate again.`));
+					}
+				}
+			}
 			const releaseAdmission = writes ? holdAdmission(toolCallId) : () => {};
 			const local: NonNullable<ReturnType<typeof directTasks.get>> = { controller, settled, handles, tabs,
 				continues: new Set([...sources.values()].map(({ sessionFile }) => sessionFile)) };
@@ -795,7 +831,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					const proof = (async () => {
 						entryControllers.get(entryId)!.abort();
 						await handle.cancel().catch(() => undefined);
-						await herdr.stop(tab, inScope);
+						await herdrFor(tab.cwd ?? ctx.cwd).stop(tab, inScope);
 					})();
 					stopProofs.set(entryId, proof);
 					return proof;
@@ -805,7 +841,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				const inScope = () => current() && (local.closeScope?.() ?? true);
 				try {
 					if (local.allocation) throw new Error(local.allocation.failure);
-					for (const tab of tabs) await herdr.stop(tab, inScope);
+					for (const tab of tabs) await herdrFor(tab.cwd ?? ctx.cwd).stop(tab, inScope);
 					if (!inScope()) throw new Error("Direct task scope changed; reopen /subagent.");
 					releaseAdmission();
 					directTasks.delete(taskId);
@@ -831,10 +867,10 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				startWidgetItem(entry.id, taskId, display, prepared.model.id, prepared.thinkingLevel, ctx);
 				const transient = await materializeTransientLaunch({ launch: prepared, prompt: prepared.systemPrompt,
 					promptArgIndex: prepared.promptArgIndex }, activeSignal);
-				snapshots.set(entry.id, await snapshotCheckout(ctx.cwd).catch((error: unknown) => error instanceof Error ? error : new Error(String(error))));
+				snapshots.set(entry.id, await snapshotCheckout(entryCwd(entry.index)).catch((error: unknown) => error instanceof Error ? error : new Error(String(error))));
 				let handle: DirectHandle;
 				try {
-					handle = await herdr.start({ ...prepared, args: [...transient.launch.args] },
+					handle = await herdrFor(targets[entry.index]!).start({ ...prepared, args: [...transient.launch.args] },
 						`d-${randomUUID().replaceAll("-", "").slice(0, 24)}`, `${directRef(display)} ${display.title}`,
 						`${entry.delegation.access === "read" ? `${entry.delegation.task}\n\n${READ_ACCESS_NOTICE}` : entry.delegation.task}\n\nFinal answer budget: ${answerBytes} bytes, conclusions first. Main sees only that much inline; a longer answer is saved to a file.`, activeSignal, (tab) => {
 							const record = { taskId, entryId: entry.id, display, ...tab };
@@ -867,7 +903,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					try {
 						await assertSettledDirectSession(source.sessionFile, source.turn);
 						// Close only an idle or done exact agent; an absent one still needs two empty lease scans.
-						await herdr.stop(source, () => launchEpoch === sessionEpoch && !controller.signal.aborted, true);
+						await herdrFor(targets[index]!).stop(source, () => launchEpoch === sessionEpoch && !controller.signal.aborted, true);
 					} catch (error) {
 						throw new Error(`Cannot continue ${workflow.delegations[index]!.continueFrom}: ${error instanceof Error ? error.message : String(error)}.`, { cause: error });
 					}