@henryqw/pi-subagent 15.1.2 → 15.1.3

package/README.md

@@ -80,6 +80,10 @@ See the [orchestration guide](./docs/orchestration.md) for full delegation, tran
 
 The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill guides Main's planning and orchestration. It adds no runtime code, config, or Role installation.
 
+Implementers remove only task-created temporary, generated, or ignored artifacts. Required deliverables and unrelated files stay intact. They never use `git clean` or blanket deletion, and unclear paths block.
+
+For known regressions with a runner that supports test-name filtering, use a test-name filter. Keep broad package or workspace checks to one caller-owned final validation after relevant units integrate. Flow itself does not run that check.
+
 Before delegating:
 
 - Find concrete outcomes that can ship on their own.

package/docs/orchestration.md

@@ -110,12 +110,12 @@ Flow has no dependency graph, saved state, automatic retry, aggregate review, or
 
 ## Per-delegation resources and isolation
 
-For `delegate_task`, every single entry, parallel sibling, and chain step independently:
+`delegate_task` first preflights every requested Role name, so an initially unknown Role starts no sibling. Then, after receiving an executor permit, every single entry, parallel sibling, and chain step independently:
 
-1. loads its selected Role;
-2. resolves its route and named Skills from the latest effective Pi context after receiving an executor permit;
+1. reloads its effective Role by requested name;
+2. resolves its route and named Skills from the latest effective Pi context;
 3. creates its Role launch policy; and
-4. when the Role requests `isolation: worktree`, creates a worktree identified by the tool call, mode, and input index.
+4. when the reloaded Role requests `isolation: worktree`, creates a worktree identified by the tool call, mode, and input index.
 
 Separate deterministic identities produce separate worktree paths and branches. Parallel siblings cannot collide, and a chain does not base one step's worktree on the preceding step's branch. `{previous}` passes text only. There is no implicit shared worktree or hidden workflow state.
 

package/examples/roles/implementer.md

@@ -16,7 +16,7 @@ isolation: worktree
 
 Implement the bounded outcome, not a preassigned file list. Work in the assigned cwd. Read applicable repository instructions and domain context first; inspect the relevant flow, callers, and tests before editing. Preserve unrelated work. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies. Do not add speculative work. Stop when the outcome is complete or blocked.
 
-For ordinary delegation, run focused validation needed to establish correctness. For Flow, the declared validation gate is authoritative: run only narrow development checks while implementing and do not duplicate that final gate.
+For ordinary delegation, run focused validation needed to establish correctness. For Flow, the declared validation gate is authoritative: run only narrow development checks while implementing and do not duplicate that final gate. Before reporting ordinary or Flow completion, remove only task-created non-deliverable temporary, generated, or ignored artifacts. Preserve required deliverables, unrelated files, pre-existing files, and user data. Never use `git clean` or blanket deletion. If a path's ownership or necessity is uncertain, report its exact path as a blocker.
 
 Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 

package/extensions/delegate-flow.ts

@@ -550,7 +550,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		const tip = oid(tipResult.stdout, "Unit HEAD");
 		const branchTip = oid(await requireGit(["rev-parse", "--verify", `refs/heads/${unit.worktree.branch}^{commit}`], unit.worktree.cwd, signal), "Unit branch tip");
 		if (tip !== branchTip) return { block: `Unit ${JSON.stringify(unit.request.id)} branch no longer names its checked-out HEAD.` };
-		const status = await requireGit(["status", "--porcelain=v1", "--untracked-files=all"], unit.worktree.cwd, signal);
+		const status = await requireGit(["status", "--porcelain=v1", "--untracked-files=all", "--ignore-submodules=none"], unit.worktree.cwd, signal);
 		if (status) return { block: `Unit Worktree is dirty:\n${capOutput(status)}` };
 		const flags = await inspectIndexFlags(unit.worktree.cwd, git, signal);
 		if (flags.failure) throw new Error(`Unit index inspection failed: ${flags.failure}`);

package/extensions/subagent.ts

@@ -619,10 +619,9 @@ export default function subagentExtension(
 			};
 			throwIfAborted();
 			let workflow: ParsedWorkflow;
-			let roles: Role[];
 			try {
 				workflow = parseWorkflow(params);
-				roles = loadRoles();
+				const roles = loadRoles();
 				const knownRoles = new Set(roles.map(({ name }) => name));
 				for (const { role } of workflow.delegations) {
 					if (!knownRoles.has(role)) {
@@ -633,7 +632,22 @@ export default function subagentExtension(
 				throw boundedError(error);
 			}
 			throwIfAborted();
-			const rolesByName = new Map(roles.map((role) => [role.name, role]));
+			const reloadRole = (name: string): Role => {
+				let freshRoles: Role[];
+				try {
+					freshRoles = loadRoles();
+				} catch (error) {
+					throw boundedError(new Error(
+						`Couldn't reload Subagent role ${JSON.stringify(name)} after it waited for an executor permit. Fix the Role configuration and retry: ${error instanceof Error ? error.message : String(error)}`,
+						{ cause: error },
+					));
+				}
+				const role = freshRoles.find((candidate) => candidate.name === name);
+				if (role) return role;
+				throw boundedError(new Error(
+					`Subagent role ${JSON.stringify(name)} disappeared while waiting for an executor permit. Restore it and retry. Available roles: ${freshRoles.map(({ name: available }) => available).join(", ") || "none"}.`,
+				));
+			};
 
 			// Resolve against the latest known session context after each FIFO permit.
 			const launchCtx = () => latestCtx ?? ctx;
@@ -681,7 +695,6 @@ export default function subagentExtension(
 			const runWorkflow = async (workflowSignal: AbortSignal | undefined, emitToolUpdates: boolean) => {
 				try {
 					return await runForegroundWorkflow<EphemeralSubagentResult>(toolCallId, foregroundWorkflow, async (entry: WorkflowEntry) => {
-					const role = rolesByName.get(entry.delegation.role)!;
 					let model: string | undefined;
 					let thinkingLevel: string | undefined;
 					let worktree: WorktreeInfo | undefined;
@@ -701,7 +714,7 @@ export default function subagentExtension(
 							id: entry.id,
 							index: entry.index,
 							name: entry.delegation.name,
-							role: role.name,
+							role: entry.delegation.role,
 							...(model === undefined ? {} : { model }),
 							...(thinkingLevel === undefined ? {} : { thinkingLevel }),
 							...(worktreePayload === undefined ? {} : { worktreePayload }),
@@ -723,6 +736,7 @@ export default function subagentExtension(
 							prepare: async () => {
 								// Route and effective Role resources resolve only after this entry's
 								// shared executor permit, before isolated state is created.
+								const role = reloadRole(entry.delegation.role);
 								const launch = resolveLaunch(role, entry.delegation);
 								notifyMissingSkills(role, launch);
 								model = modelReference(launch.model);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "15.1.2",
+  "version": "15.1.3",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent-delegated-development/SKILL.md

@@ -17,7 +17,7 @@ Before selecting a Flow unit, require that one Implementer launch can plausibly
 
 Give every unit a bounded objective, owned scope and exclusions, and its direct validation command/argument array. Each task packet must name the neighboring behavior that must stay unchanged. Include the exact test name or error when known CI evidence exists. Never claim a validation command matches unknown CI.
 
-Each delegation must own one concrete outcome with one focused validation story. Order declared validation from the cheapest focused check to broader required checks. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Do not pass the parent request unchanged. Choose `modelClass` according to the delegation tool's guidance. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
+Each delegation must own one concrete outcome with one focused validation story. When a known regression exists and the runner supports test-name filtering, require its exact test-name filter for that unit; for Node, use `node --test --test-name-pattern "exact test name" test/example.test.ts`. Keep each unit's declared validation focused on that unit's outcome; do not include a broad package or workspace suite. Its declared Flow validation remains authoritative for that outcome. Reserve required broad package or cross-unit checks for one distinct caller-owned final integration validation after relevant units integrate. Do not duplicate checks against the same state. Flow itself has no post-merge validation. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Do not pass the parent request unchanged. Choose `modelClass` according to the delegation tool's guidance. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
 
 ## Runtime Flow