pi-herdr-agents 0.1.2 → 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/orchestrated-review-workflow-plan.md

@@ -317,13 +317,18 @@ The full bounded `RunEnvelope` exists exactly once, inside the single terminal e
 ```text
 approved
 started
+reader_checkout_ready | reader_checkout_retained | reader_checkout_disposed
 agent_started
+agent_completed
 agent_result
+pane_close_failed
 workflow_log
 completed | failed | cancelled | interrupted
 delivery
 ```
 
+`agent_completed` records the observed child exit, session availability, final assistant-text length, and (when present) final stop reason before the corresponding `agent_result` records the workflow-facing success or failure envelope.
+
 `delivery` follows the terminal event and contains only its terminal-event ID/state, target parent session, attempt time, and `sent | failed` delivery status. It never duplicates the task result. Evidence readers obtain the result from the referenced terminal event. Do not add mutable snapshots, locks, leases, backups, call caching, or replay.
 
 One process-global owner records the run ID, canonical project identity, lifecycle gate, Worker, and private child handles. `/new`, `/resume`, and `/fork` cannot start a second workflow while this owner exists; cancellation names the run ID and must match the current canonical project identity. On same-process `/reload`, the owner and Worker continue, and completion selects the latest extension API once. On full startup, scan only direct child directories under the current project's `.pi/plans/` and inspect only each journal's last valid event. A `delivery` event carries its referenced terminal state, a terminal event is already settled, and a non-terminal running event with no live process-global owner receives one `interrupted` terminal event. Do not recurse, restart, clean, or expose history UI.

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.2",
+  "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

@@ -85,6 +85,7 @@ import {
 
 import {
 	findLastAssistantMessage,
+	inspectFinalAssistantMessage,
 	findObservedSessionRuntime,
 	getNewEntries,
 	seedSubagentSessionFile,
@@ -790,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
@@ -955,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,
@@ -1125,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");
 }
 
@@ -1993,6 +2024,7 @@ export const __test__ = {
 	sendSubagentResult,
 	resolveResumeLaunchBehavior,
 	shouldRetainSubagentSurface,
+	resolveWorktreeLaunchWarning,
 	captureWorktreeHandoff,
 	runSubagentScript,
 	writeWorktreeManifest,
@@ -3033,18 +3065,43 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			if (childController.signal.aborted || watched.error === "cancelled") {
 				return workflowFailure("cancelled", "Workflow cancelled.");
 			}
-			const childEntries = existsSync(sessionFile)
+			const sessionExists = existsSync(sessionFile);
+			const childEntries = sessionExists
 				? getNewEntries(sessionFile, 0)
 				: [];
-			const summary = findLastAssistantMessage(childEntries);
-			if (watched.exitCode !== 0 || watched.errorMessage || !summary) {
+			const finalAssistant = inspectFinalAssistantMessage(childEntries);
+			journal.append("agent_completed", {
+				id,
+				role: roleName,
+				sessionFile,
+				sessionExists,
+				exitCode: watched.exitCode,
+				...(watched.errorMessage
+					? { errorMessage: watched.errorMessage }
+					: {}),
+				finalAssistantContentLength: finalAssistant.contentLength,
+				...(finalAssistant.stopReason
+					? { finalAssistantStopReason: finalAssistant.stopReason }
+					: {}),
+			});
+			if (watched.exitCode !== 0 || watched.errorMessage) {
 				return workflowFailure(
 					"child_error",
 					watched.errorMessage ??
-						summary ??
 						`Workflow child exited with code ${watched.exitCode}`,
 				);
 			}
+			if (!finalAssistant.text) {
+				return workflowFailure(
+					"empty_completion",
+					`Workflow child completed without assistant text${
+						finalAssistant.stopReason
+							? ` (stopReason: ${finalAssistant.stopReason})`
+							: ""
+					}.`,
+				);
+			}
+			const summary = finalAssistant.text;
 			const observed = findObservedSessionRuntime(childEntries);
 			const observedModel =
 				observed.provider && observed.modelId
@@ -3717,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,
@@ -3844,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.`,
@@ -3860,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",
 					},
 				};

package/pi-extension/subagents/session.ts

@@ -136,6 +136,39 @@ export function findObservedSessionRuntime(entries: SessionEntry[]): ObservedSes
   return observed;
 }
 
+export interface FinalAssistantMessage {
+  text: string | null;
+  contentLength: number;
+  stopReason?: string;
+}
+
+/** Inspect only the final assistant message for workflow completion evidence. */
+export function inspectFinalAssistantMessage(
+  entries: SessionEntry[],
+): FinalAssistantMessage {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "message") continue;
+    const msg = entry as MessageEntry;
+    if (msg.message.role !== "assistant") continue;
+
+    const texts = msg.message.content
+      .filter(
+        (block) =>
+          block.type === "text" && typeof block.text === "string",
+      )
+      .map((block) => block.text as string);
+    const text = texts.join("\n");
+    const stopReason = (msg.message as { stopReason?: unknown }).stopReason;
+    return {
+      text: text.trim() ? text : null,
+      contentLength: text.length,
+      ...(typeof stopReason === "string" ? { stopReason } : {}),
+    };
+  }
+  return { text: null, contentLength: 0 };
+}
+
 export function findLastAssistantMessage(entries: SessionEntry[]): string | null {
   for (let i = entries.length - 1; i >= 0; i--) {
     const entry = entries[i];