pi-herdr-agents 0.1.3 → 0.1.4

package/README.md

@@ -370,6 +370,8 @@ subagent({
 
 Use one worktree per independent writing task; keep read-only agents in ordinary panes. `cwd` selects the source Git repository, `branch` must be unique, and `base` is resolved to an exact commit before creation. If `base` is omitted, the source checkout's committed `HEAD` is used. Parent-checkout changes that have not been committed are not copied.
 
+A launch with `worktree` and an effective bundled `scout`, `reviewer`, or `adversarial-reviewer` returns a non-blocking warning. Scouts and reviewers normally need an ordinary pane; the adversarial reviewer is a coordinator that normally uses an ordinary pane for its review artifacts and child reviewers. To inspect or review an existing worker result, start an ordinary child in that retained worktree path. Project or global role overrides do not receive these bundled-role warnings.
+
 The child starts at the returned worktree root. Tell writing agents to test and commit when you want a commit-based handoff, and tell them not to push, merge, switch branches, or remove the worktree. The parent owns review and integration.
 
 Successful, failed, and help-requesting runs retain their workspace. Completion includes the worktree path, Herdr workspace, branch, base/head SHAs, commits ahead, changed and untracked files, and clean/dirty/conflicted state. Here, `clean` means no uncommitted files; the branch may still contain commits. If Git inspection fails, state is reported as unknown rather than guessed.

package/docs/worktree-subagents.md

@@ -121,7 +121,27 @@ The parent receives the normal child summary plus:
 
 `clean` means there are no staged, unstaged, or untracked files. It does **not** mean the branch has no commits or diff relative to its base.
 
-If Git inspection fails, SHA/count/state/file fields are reported as unknown rather than guessed, and the warning is included in the handoff. Inspect the retained workspace directly before integrating or deleting it.
+If Git inspection fails, SHA/count/state/file fields are reported as unknown rather than guessed, and the warning is included in the handoff. Inspect the retained workspace directly before integrating or deleting it. Every retained handoff also includes the exact `herdr worktree remove --workspace <workspace-id>` command, but run it only after useful state is preserved.
+
+## Parallel pull-request review without new worktrees
+
+For parallel read-only review, prepare one stable existing checkout of the pull request or retained worker result. Do not create one managed worktree per reviewer.
+
+1. The parent records the exact base and head SHAs and makes sure no writer changes the checkout while review runs.
+2. Start each read-only child in an ordinary pane with `cwd` set to that checkout. Omit `worktree`.
+3. Give every reviewer the same exact base and head SHAs. Require it to report `git rev-parse HEAD` before its review result.
+4. Before the parent reports or publishes the review, recheck the checkout SHA. If it changed, treat the prior reviews as stale and review the new commit again.
+
+```typescript
+subagent({
+  name: "PR reviewer",
+  agent: "reviewer",
+  cwd: "/path/to/pr-checkout",
+  task: "Review base <base-sha> through head <head-sha>. First report git rev-parse HEAD. Do not modify files.",
+});
+```
+
+A retained worker worktree can be this checkout. The parent owns any final report, PR action, integration, and cleanup.
 
 ## Review and integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/index.ts

@@ -791,7 +791,7 @@ function resolveEffectiveInteractive(
 function loadAgentDefaults(
 	agentName: string,
 	pi?: Pick<ExtensionAPI, "events">,
-): AgentDefaults | null {
+): ListedAgentDefinition | null {
 	return (
 		discoverAgentCatalog(pi).agents.find((agent) => agent.name === agentName) ??
 		null
@@ -956,6 +956,32 @@ function shouldRetainSubagentSurface(
 	return !!running.worktree;
 }
 
+const BUNDLED_WORKTREE_WARNINGS: Readonly<Record<string, string>> = {
+	scout:
+		"The bundled scout role is read-only and normally does not need a new worktree. " +
+		"Use an ordinary pane instead; to inspect an existing worker result, start it in the retained worktree path. " +
+		"Herdr worktree workspaces persist until explicitly removed.",
+	reviewer:
+		"The bundled reviewer role is read-only and normally does not need a new worktree. " +
+		"Use an ordinary pane instead; to review an existing worker result, start it in the retained worktree path. " +
+		"Herdr worktree workspaces persist until explicitly removed.",
+	"adversarial-reviewer":
+		"The bundled adversarial-reviewer coordinates read-only reviewers and writes review artifacts. " +
+		"It normally uses an ordinary pane, not a new worktree. " +
+		"Herdr worktree workspaces persist until explicitly removed.",
+};
+
+function resolveWorktreeLaunchWarning(
+	params: Pick<Static<typeof SubagentParams>, "agent" | "worktree">,
+	pi?: Pick<ExtensionAPI, "events">,
+): string | undefined {
+	if (!params.worktree || !params.agent) return undefined;
+	const warning = BUNDLED_WORKTREE_WARNINGS[params.agent];
+	return warning && loadAgentDefaults(params.agent, pi)?.source === "package"
+		? warning
+		: undefined;
+}
+
 function runSubagentScript(
 	surface: string,
 	command: string,
@@ -1126,6 +1152,10 @@ function formatWorktreeHandoff(worktree: WorktreeHandoff): string {
 		lines.push(`Untracked: ${worktree.untrackedFiles.join(", ")}`);
 	if (worktree.gitError)
 		lines.push(`Git inspection warning: ${worktree.gitError}`);
+	lines.push(
+		"After review and preservation, remove the workspace with:",
+		`  herdr worktree remove --workspace ${worktree.workspaceId}`,
+	);
 	return lines.join("\n");
 }
 
@@ -1994,6 +2024,7 @@ export const __test__ = {
 	sendSubagentResult,
 	resolveResumeLaunchBehavior,
 	shouldRetainSubagentSurface,
+	resolveWorktreeLaunchWarning,
 	captureWorktreeHandoff,
 	runSubagentScript,
 	writeWorktreeManifest,
@@ -3743,6 +3774,10 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					ctx,
 					parentThinking,
 				);
+				const worktreeLaunchWarning = resolveWorktreeLaunchWarning(
+					params,
+					runtime.pi,
+				);
 				const { running, index: initialPlanIndex } = await launchSubagentWithFallbacks(
 					params,
 					ctx,
@@ -3870,6 +3905,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 								(running.worktree
 									? ` in worktree ${running.worktree.path} on branch ${running.worktree.branch}. `
 									: ". ") +
+								(worktreeLaunchWarning
+									? `Warning: ${worktreeLaunchWarning} `
+									: "") +
 								`Do NOT generate or assume any results — you have no idea what the sub-agent will do or produce. ` +
 								`The results will be delivered to you automatically as a steer message when the sub-agent finishes. ` +
 								`Until then, move on to other work or tell the user you're waiting.`,
@@ -3886,6 +3924,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 						thinking: running.runtimePlan?.thinking,
 						runtimePlan: running.runtimePlan,
 						...(running.worktree ? { worktree: running.worktree } : {}),
+						...(worktreeLaunchWarning
+							? { warning: worktreeLaunchWarning }
+							: {}),
 						status: "started",
 					},
 				};