@henryqw/pi-subagent 27.7.0 → 27.9.0

package/README.md

@@ -25,13 +25,14 @@ Configure the profiles that your Roles use in `/task-models`. Direct writer term
 
 Ask Main: “Have a scout trace sign-in without editing files.” Main calls `delegate_task` and stays available until progress and results arrive.
 
-Commands and UI are for you. Tools and the packaged skill are for Main, except `git_read`, which is only for Role-declared children.
+Commands, prompts, and UI are for you. Tools and the packaged skill are for Main, except `git_read`, which is only for Role-declared children.
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | `/subagent` | command | Browse direct and isolated work, including requests whose parent checkout was removed. Stop direct workers, inspect isolated work, send follow-ups, or delete owned isolated worktrees after confirmation. **Select multiple…** applies one action to many rows. Without interactive UI, only reports. |
 | `/subagent roles` | command | List Role sources, resources, resolved model and thinking level, route errors, and file errors. Read-only; requires no Herdr pane. |
 | `/subagent prune` | command | Review remaining worker and integration branches and worktrees. Select the items to remove; merged items are selected first. Some blocked items can also be selected, after a separate confirmation. Requires a running Herdr server; without interactive UI, only reports. |
+| `/review [target] [focus]` | prompt | Tell Main to review a change with parallel `reviewer` tasks and give one ship verdict. See [Review a change](#review-a-change). |
 | `/subagent recover` | command | Classify interrupted isolated work in the canonical repository. Send Main request IDs, blockers, and next actions. Requires no UI or Herdr pane. |
 | `delegate_task` | tool | Start authorized shared-checkout work or a durable isolated checked graph. With `dryRun: true`, check the request and show the resolved plan without a launch. |
 | `subagent_status` | tool | Read saved isolated state, exact identities, failed review verdicts, and allowed continuation. Does not replay work. Supports structured output for `codemode`. |
@@ -90,6 +91,21 @@ The launch returns a task ID and first Herdr tab, not the answer. One follow-up
 
 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 eligibility and stop behavior, see [Continue or stop one direct worker](./docs/orchestration.md#continue-or-stop-one-direct-worker).
 
+### Review a change
+
+Run `/review` to review uncommitted changes against `HEAD`. To review other work, give one target:
+
+| Target | Reviewed change |
+| --- | --- |
+| `A..B` | From `A` to `B` |
+| `feature-branch` | From the merge-base with `main` to the branch |
+| `a1b2c3d` | The commit against its first parent |
+| `#42` | The pull request head against its merge-base with the pull request base |
+
+Text after the target adds a review focus, for example `/review #42 cache invalidation`. If the first word is not a target, Main reviews uncommitted changes and uses all text as the focus. Main changes the target to exact local commit IDs. Reviewers can read only local Git. So, for a pull request, Main fetches the head and base from the pull request repository to `refs/pi-review/`. Main groups changed files by location, starts one read-only `reviewer` task for each group, and merges the findings.
+
+The verdict is **Ship** only if each reviewer task succeeded and answered exactly `PASS`. Otherwise, the verdict is **Do not ship**, with the findings in priority order. If the checkout changed during a review task, the verdict is also **Do not ship**, and you must run the review again. Main does not fix findings. If another `/review` prompt template loads first, Pi keeps that template and reports a name collision.
+
 ### Isolated workflow
 
 ![Isolated workers commit checked candidates; Main stages ready work while siblings run, advances dependents, validates the combined tip, and explicitly promotes](./docs/orchestration-architecture.svg)
@@ -139,6 +155,10 @@ The extension sends follow-ups when a candidate becomes ready, a worker needs at
 
 Open `/subagent` to browse direct work on this session branch and isolated requests in the current canonical Git checkout, including other sessions. The menu groups rows under **Direct**, **Isolated**, and **Orphaned** headers. Each isolated row shows the request ID, the status, and a short goal summary. **Refresh** or a header reloads saved status without recovery or mutation. Invalid state IDs stay preserved with a warning. Direct recovery remains available outside Git or without isolated inventory.
 
+Before the menu opens, and after each **Refresh**, a **Current subagent work** report shows which subagents are working. The extension calculates it from local and saved evidence without a model call. Without interactive UI, `/subagent` sends this report before the request list.
+
+A direct workflow is working only when this Pi process owns it and has a running worker. Direct work with a delivered result shows its outcome under **Completed / history** and is not in the report. Other recorded-only direct work shows as unverified. An isolated request is working only when its status is active and a live run holds the repository lease. Without a live lease, an active request shows as interrupted; run `/subagent recover`.
+
 Each row starts with a status symbol: `●` active, `✓` completed, `⚠` needs attention, `✗` failed. In the terminal UI, `/subagent` reports (Roles, details, reviews, and results) show as colored transcript entries. The model does not get these entries. In RPC mode, they show as notifications. Without interactive UI, they show as plain text messages.
 
 Requests whose parent checkout was removed show in the **Orphaned · parent checkout removed** group from any checkout of the same repository. Every isolated request, including an orphaned request, has **Close and delete worktrees (discard work)**. Select it to review owned resources and confirm deletion. **This permanently deletes committed, uncommitted, and ignored content in the listed checkouts.** Cancel makes no change.
@@ -196,6 +216,12 @@ Role Markdown files in `~/.pi/agent/config/pi-subagent/` require frontmatter and
 
 The package ships `implementer`, `reviewer`, and `scout`; same-name user Roles override built-ins. Roles define capabilities, not access or isolation. Unknown frontmatter keys invalidate that file and report its path and key. Other valid Roles load; duplicate names become unavailable. Delegation to an invalid file's claimed Role fails with that file's error. Inspect `/subagent roles`.
 
+The built-in reviewer answers exactly `PASS` when it finds no actionable correctness risk. Otherwise, each finding starts with a priority and a confidence (`high`, `medium`, or `low`), for example `[P1] confidence: high`. Then it gives file and line evidence, the trigger, the impact, and the smallest fix. Each finding blocks approval.
+
+- `P0`: breaks release or operation on ordinary input.
+- `P1`: wrong behavior under a realistic condition.
+- `P2`: wrong behavior in a narrow edge case with limited impact.
+
 The built-in reviewer and scout include `git_read`; existing user reviewers and scouts must add it to `tools`. No additional extension or Bash access is necessary. See [Reviewer Git inspection](./docs/orchestration.md#reviewer-git-inspection) for operations, parameters, limits, and Git requirements.
 
 Children load only declared resources and required adapters. Roles must list their model provider extension. `codemode` requires both `builtin:codemode` in `extensions` and `codemode` in `tools`. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work. Main-only delegation/recovery tools and `ask_question` stay unavailable to children.

package/dist/runner.d.ts

@@ -332,6 +332,8 @@ export declare class IsolatedRunner {
         invalidIds: string[];
         states: RunState[];
     }>;
+    /** True while a live productive run holds this root's lease; the lease does not name its request. */
+    hasProductiveRunLease(root: string): Promise<boolean>;
     /** Classify orphaned work under the same repository lease as productive execution.
      * Status remains read-only; Main alone chooses any subsequent action. */
     recoverRepository(root: string): Promise<{

package/dist/runner.js

@@ -639,6 +639,10 @@ export class IsolatedRunner {
                 })),
             })) };
     }
+    /** True while a live productive run holds this root's lease; the lease does not name its request. */
+    async hasProductiveRunLease(root) {
+        return await this.store.hasProductiveRunLease(root);
+    }
     /** Classify orphaned work under the same repository lease as productive execution.
      * Status remains read-only; Main alone chooses any subsequent action. */
     async recoverRepository(root) {

package/docs/orchestration.md

@@ -269,7 +269,7 @@ After readiness, use `subagent_stage revise` with the exact candidate, generatio
 
 ### Inspect and revise active work
 
-To select work by label, open `/subagent` without arguments. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout. This includes requests launched in other sessions. Select an isolated request. Then select **Inspect status and recovery**.
+To select work by label, open `/subagent` without arguments. First, a **Current subagent work** report shows the work that local and saved evidence proves is running: locally owned direct workflows with a running worker, and active isolated requests while a live run holds the repository lease. The report lists active requests without a live lease as interrupted, and recorded-only direct work as unverified. A live lease does not identify its request, so several active requests in one checkout all show as working. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout. This includes requests launched in other sessions. Select an isolated request. Then select **Inspect status and recovery**.
 
 The menu also shows requests whose saved parent checkout no longer exists, in their own **Orphaned · parent checkout removed** group. You can open this view from any checkout of the same repository. The saved worker or integration path identifies the primary repository. Orphaned requests have the same **Close and delete worktrees (discard work)** action, but no inspection or follow-up actions. The extension reads their original state directories; it does not recreate the removed parent checkout. Unreadable files stay preserved and are reported.
 

package/examples/roles/reviewer.md

@@ -16,4 +16,10 @@ Review the supplied candidate read-only. Use only supplied requirements and name
 
 Report only actionable correctness risks introduced by the change, not style preferences, speculative hypotheticals, or unrelated pre-existing issues. Run no tests or commands outside `git_read`. Never edit, write, commit, push, mutate Git or manage worktrees, or invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-Output exactly `PASS` when there are no findings. Otherwise output findings only, ordered by severity, with file:line evidence, impact, and the smallest valid fix. Any finding blocks approval; never combine `PASS` with findings. Stop when the supplied evidence is covered.
+Output exactly `PASS` when there are no findings. Otherwise output findings only, ordered by priority, then confidence. Start each finding with its priority and confidence, for example `[P1] confidence: high`, then give file:line evidence, the trigger, the impact, and the smallest valid fix:
+
+- `P0`: breaks release or operation on ordinary input, such as data loss, a security bypass, or a crash.
+- `P1`: wrong behavior under a realistic condition, such as a race, a missed error path, or a broken caller.
+- `P2`: wrong behavior in a narrow edge case with limited impact.
+
+Confidence is `high`, `medium`, or `low` that the defect is real; name the affected code path even when low. Any finding blocks approval; never combine `PASS` with findings. Stop when the supplied evidence is covered.

package/extensions/isolated.ts

@@ -842,7 +842,8 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 				catch (error) { console.error("Pi Subagent workspace widget update failed.", error); }
 			}
 			const orphans = await getComponents().runner.listOrphanRequests(root);
-			return { root, requests: [...requests, ...orphans.requests], invalidIds: [...new Set([...invalidIds, ...orphans.invalidIds])] };
+			const leaseLive = await getComponents().runner.hasProductiveRunLease(root);
+			return { root, leaseLive, requests: [...requests, ...orphans.requests], invalidIds: [...new Set([...invalidIds, ...orphans.invalidIds])] };
 		},
 		async recover(cwd) {
 			const root = await lookupRoot(cwd);

package/extensions/subagent-command.ts

@@ -56,6 +56,8 @@ export interface IsolatedRequest {
 }
 export interface IsolatedInventory {
 	root: string;
+	/** A live productive run holds this root's lease; the lease does not name its request. */
+	leaseLive: boolean;
 	requests: readonly IsolatedRequest[];
 	invalidIds: readonly string[];
 }
@@ -291,6 +293,41 @@ function directReport(task: DirectTask): Report {
 	] };
 }
 
+const WORKING_REPORT_CODE_POINTS = 4_000;
+/** Current work from local and saved evidence only. Recorded-only direct work and isolated work without a live lease never count as working. */
+export function workingReport(direct: readonly DirectTask[], inventory: IsolatedInventory | undefined): Report {
+	const working: Row[] = [];
+	const attention: Row[] = [];
+	const unverified: Row[] = [];
+	for (const task of direct) {
+		const text = `${directLabel(task)} · ${task.status}`;
+		// Read workflows list their running workers; write workflows stay observed locally until their workers are proved stopped.
+		if (task.status === "observed locally" && task.stoppable?.length !== 0) working.push({ text: task.stoppable ? `${directLabel(task)} · ${task.stoppable.length} running` : text });
+		else if (/retained|attention/.test(task.status)) attention.push({ text });
+		else if (completed(task.status)) continue;
+		else unverified.push({ text: task.status === "observed locally" ? `${text}; no running worker` : text });
+	}
+	for (const request of inventory?.requests ?? []) {
+		const active = !request.orphaned && ["pending", "running"].includes(request.status);
+		if (active && inventory!.leaseLive) working.push({ text: isolatedLabel(request) });
+		else if (active) attention.push({ text: `${isolatedLabel(request)} · interrupted; run /subagent recover` });
+		else if (!request.orphaned && (request.status === "needs_attention" || /retained/.test(request.status))) attention.push({ text: isolatedLabel(request) });
+	}
+	const sections: Section[] = [
+		working.length ? { heading: `Working (${working.length})`, tone: "info", rows: working } : { rows: [{ text: inventory ? "No subagents are working." : "No direct subagents are working. Isolated status is unavailable." }] },
+		{ heading: `Needs attention (${attention.length})`, tone: "warning", rows: attention },
+		{ heading: `Unverified (${unverified.length})`, note: "not proof of running or completion", tone: "warning", rows: unverified },
+	];
+	const head: Report = { tone: attention.length ? "warning" : "info", title: "Current subagent work", sections: [] };
+	const items = sections.flatMap((section) => section.rows.map((row, index) => ({ section, index, row })));
+	const fitted = fitItems(reportMarkdown(head), items, ({ section, index, row }) => index ? sectionMarkdown({ rows: [row] }) : `\n${sectionMarkdown({ ...section, rows: [row] })}`,
+		WORKING_REPORT_CODE_POINTS, "open /subagent with interactive UI to see them.");
+	return { ...head, sections: [...sections.flatMap((section) => {
+		const rows = fitted.shown.filter((item) => item.section === section).map(({ row }) => row);
+		return rows.length ? [{ ...section, rows }] : [];
+	}), ...moreSection(fitted.more)] };
+}
+
 type Choice<T> = { label: string; value: T };
 async function choose<T>(ctx: ExtensionContext, title: string, items: readonly Choice<T>[]): Promise<T | undefined> {
 	// Numeric suffixes only tell duplicate labels apart. Never parse display text into an identity.
@@ -462,6 +499,7 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 			}
 			if (!ctx.hasUI) {
 				const inventory = await adapter.isolated(ctx.cwd, current);
+				deliver(ctx, workingReport(adapter.direct(ctx), inventory));
 				const head: Report = { tone: "info", title: "Isolated requests (report only)", sections: [] };
 				const row = (request: IsolatedRequest): Row => ({ text: `${glyph(request.status)} ${request.orphaned ? "orphaned · " : ""}${isolatedLabel(request)}` });
 				const listed = fitItems(`${reportMarkdown(head)}\n`, inventory.requests, (request) => sectionMarkdown({ rows: [row(request)] }), ROLES_REPORT_CODE_POINTS,
@@ -473,6 +511,8 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				return;
 			}
 			let history = false;
+			// The working report shows on open and on each Refresh, not after other menu actions.
+			let report = true;
 			for (;;) {
 				if (!valid()) return;
 				// Direct recovery is independent of Git and isolated config/inventory failures.
@@ -482,6 +522,8 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				try { inventory = await adapter.isolated(ctx.cwd, current); }
 				catch (error) { unavailable = errorText(error); }
 				if (!valid()) return;
+				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");
 				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" };
@@ -509,7 +551,7 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				if (!unavailable && !direct.length && !inventory?.requests.length && !inventory?.invalidIds.length) ctx.ui.notify("No direct tasks recorded on this session branch or isolated requests in this checkout. Ask Main to start delegation.", "info");
 				const selected = await choose(ctx, history ? "Subagent · completed / history" : "Subagent · current work", selections);
 				if (!valid() || !selected || selected.kind === "close") return;
-				if (selected.kind === "refresh") continue;
+				if (selected.kind === "refresh") { report = true; continue; }
 				if (selected.kind === "history") { history = !history; continue; }
 				if (selected.kind === "many") {
 					const picked = await chooseMany(ctx, "Subagent · select work", rows.map(({ label, value }) => ({ label: label.trim(), value })), [], valid);

package/extensions/subagent.ts

@@ -300,7 +300,10 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				const local = directTasks.get(record.taskId);
 				let task = grouped.get(record.taskId);
 				if (!task) grouped.set(record.taskId, task = { id: record.taskId, name: record.taskId,
-					status: local?.recovery ? "admission retained" : local ? "observed locally" : "recorded only; not proof of running or completion",
+					status: local?.recovery ? "admission retained" : local ? "observed locally"
+						// A recovery result did not prove worker termination, so it stays visible for recovery.
+						: results.get(record.taskId)?.recovery ? "needs attention: worker termination unproved"
+						: results.get(record.taskId)?.outcome ?? "recorded only; not proof of running or completion",
 					...(results.get(record.taskId)?.cost === undefined ? {} : { cost: results.get(record.taskId)!.cost }),
 					...(local?.recovery ? { recovery: local.recovery } : {}), canClose: Boolean(local?.close),
 					...(local?.stopWorker ? { stoppable: local.stopWorker.running() } : {}), workers: [], tabs: [] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "27.7.0",
+  "version": "27.9.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -19,6 +19,7 @@
     "extensions",
     "docs",
     "examples",
+    "prompts",
     "example.png",
     "README.md",
     "CONTEXT.md",
@@ -63,6 +64,9 @@
     "skills": [
       "./skills"
     ],
+    "prompts": [
+      "./prompts"
+    ],
     "image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-subagent/example.png"
   },
   "dependencies": {

package/prompts/review.md

@@ -0,0 +1,20 @@
+---
+description: Review a change with parallel reviewer Subagents and give one ship verdict.
+argument-hint: "[A..B | branch | commit | #PR] [focus]"
+---
+
+Review this target with parallel `reviewer` Subagents: $@
+
+Do not edit files, fix findings, commit, or push.
+
+1. Resolve the first argument to exact local commit IDs with Git. Treat the remaining text as extra review focus. If the first argument is not `#N` and does not resolve as a ref or range, use the empty target and treat all text as focus.
+   - Empty: uncommitted staged, unstaged, and untracked changes against `HEAD`.
+   - `A..B`: base `A`, tip `B`.
+   - Branch: base is `git merge-base main <branch>`, tip is the branch.
+   - Commit: base is its first parent, tip is the commit.
+   - `#N`: run `gh pr view N --json url,baseRefName`. The base repository URL is `url` without `/pull/N`. Run `git fetch <repository URL> +refs/heads/<baseRefName>:refs/pi-review/pr-N-base +refs/pull/N/head:refs/pi-review/pr-N`. Base is the merge-base of the two refs; tip is `refs/pi-review/pr-N`. Reviewers read only local Git, so fetch before delegation.
+   If the target is ambiguous or has no changes, stop and report.
+2. List the changed files, and mark untracked files. Group them by locality: same directory or module, related behavior, and tests with their implementation. Use one group for a small change and at most 5 groups.
+3. Start one `delegate_task` call with `mode: "direct"` and one `tasks` entry per group: `role: "reviewer"`, a short unique `name` (at most 29 characters), `access: "read"`, and a `task` that gives the base and tip commit IDs, its exact file list, and the criteria. For uncommitted changes, give `HEAD` <ID> instead, and tell the reviewer to combine `git_read` diff in `staged` and `working` modes and to read each marked untracked file whole with `read`. Criteria: report actionable correctness risks that the change introduces in these files, with the reviewer finding format; read other files only as context; output exactly `PASS` when there are no findings. Add the extra focus, if any.
+4. When the result arrives, merge the findings: remove duplicates that share a root cause and keep the highest priority, then sort by priority (`P0`, `P1`, `P2`) and confidence. Keep file:line evidence and fixes.
+5. Give one verdict. **Ship** only if every reviewer task succeeded and answered exactly `PASS`. Otherwise **Do not ship**, with the merged findings and any failed or incomplete reviewer task. If any result reports `checkout changed during task`, the verdict is **Do not ship**; rerun the review.