@hcflabs/pi-subagent 0.0.0-stage → 27.10.7

package/extensions/workflow.ts

@@ -0,0 +1,336 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import { posix } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { DISPLAY_TEXT_CONTRACT } from "@hcflabs/pi-subagent";
+import { PROFILE_NAMES } from "@hcflabs/pi-task-models";
+import { Type, type Static } from "typebox";
+import { Check, Errors } from "typebox/value";
+import { runGit } from "../dist/git-process.js";
+import { ExecuteRequestSchema, parseExecuteRequest, type ExecuteRequest } from "../dist/schema.js";
+
+export const MAX_WORKFLOW_ENTRIES = 8;
+
+const TASK_NAME_MAX_LENGTH = 29;
+const TaskNameSchema = Type.String({
+	minLength: 1,
+	maxLength: TASK_NAME_MAX_LENGTH,
+	description: `Short descriptive task name, about five words and fewer than ${TASK_NAME_MAX_LENGTH + 1} characters; C0/C1 control characters are rejected.`,
+	pattern: DISPLAY_TEXT_CONTRACT.pattern,
+});
+
+const RoleSchema = Type.String({ minLength: 1, pattern: DISPLAY_TEXT_CONTRACT.pattern, description: "Configured Subagent role name" });
+const TaskSchema = Type.String({ minLength: 1, description: "Bounded task packet" });
+const ModelSchema = Type.String({ minLength: 1, pattern: DISPLAY_TEXT_CONTRACT.pattern, description: "Designated model as provider/modelId; replaces the selected route model" });
+const ModelClassSchema = StringEnum(PROFILE_NAMES, { description: "Task model profile" });
+const DirectKindSchema = StringEnum(["text"] as const);
+/** Main's honest per-task classification; only `write` reserves the checkout. Nothing enforces `read`. */
+export const DIRECT_ACCESS = ["read", "write"] as const;
+export type DirectAccess = (typeof DIRECT_ACCESS)[number];
+const ACCESS_GUIDANCE = `Declare "write" when the task may change files, Git state, or external resources, otherwise "read". "read" is not enforced (no sandbox): it skips checkout admission and runs concurrently. Use mode isolated for checked writes.`;
+const AccessSchema = StringEnum(DIRECT_ACCESS, { description: ACCESS_GUIDANCE });
+const DryRunSchema = Type.Boolean({ description: "Optional. When true, run every launch validation and return the resolved plan without starting workers, saving state, or reserving the checkout." });
+const ContinueFromSchema = Type.String({ pattern: "^D[1-9][0-9]*\\.[1-9][0-9]*$", description: "Optional direct worker reference such as D7.1. Continues that finished worker's Pi session in a new tab with this task; role must equal the recorded Role." });
+
+const PathsSchema = Type.Array(Type.String({ minLength: 1 }), {
+	minItems: 1,
+	maxItems: 32,
+	description: "Write tasks only: repo-relative globs (Node path.matchesGlob syntax, such as src/**) the task may change. The result flags changed paths outside them. Report only; nothing enforces it.",
+});
+
+export const DelegationSchema = Type.Object({
+	role: RoleSchema,
+	name: TaskNameSchema,
+	task: TaskSchema,
+	access: AccessSchema,
+	paths: Type.Optional(PathsSchema),
+	continueFrom: Type.Optional(ContinueFromSchema),
+	kind: Type.Optional(DirectKindSchema),
+	model: Type.Optional(ModelSchema),
+	modelClass: Type.Optional(ModelClassSchema),
+}, { additionalProperties: false });
+
+export const DirectWorkflowSchema = Type.Object({
+	mode: Type.Literal("direct"),
+	role: Type.Optional(RoleSchema),
+	name: Type.Optional(TaskNameSchema),
+	task: Type.Optional(TaskSchema),
+	access: Type.Optional(AccessSchema),
+	paths: Type.Optional(PathsSchema),
+	continueFrom: Type.Optional(ContinueFromSchema),
+	kind: Type.Optional(DirectKindSchema),
+	model: Type.Optional(ModelSchema),
+	modelClass: Type.Optional(ModelClassSchema),
+	tasks: Type.Optional(Type.Array(DelegationSchema, { minItems: 1, maxItems: MAX_WORKFLOW_ENTRIES })),
+	chain: Type.Optional(Type.Array(DelegationSchema, { minItems: 1, maxItems: MAX_WORKFLOW_ENTRIES })),
+}, { additionalProperties: false, description: "Direct mode: exactly one compact single, tasks, or chain workflow" });
+
+// Parse each mode with its strict schema; expose a plain object root to tool providers.
+export const DelegateTaskParameters = Type.Object({
+	...DirectWorkflowSchema.properties,
+	mode: Type.Union([DirectWorkflowSchema.properties.mode, ExecuteRequestSchema.properties.mode]),
+	id: Type.Optional(ExecuteRequestSchema.properties.id),
+	goal: Type.Optional(ExecuteRequestSchema.properties.goal),
+	tasks: Type.Optional(Type.Union([
+		Type.Array(DelegationSchema, { minItems: 1, maxItems: MAX_WORKFLOW_ENTRIES }),
+		ExecuteRequestSchema.properties.tasks,
+	])),
+	finalChecks: ExecuteRequestSchema.properties.finalChecks,
+	finalJudgment: ExecuteRequestSchema.properties.finalJudgment,
+	dryRun: Type.Optional(DryRunSchema),
+}, { additionalProperties: false });
+
+export type Delegation = Static<typeof DelegationSchema> & { kind: "text" };
+export type WorkflowMode = "single" | "parallel" | "chain";
+export type ParsedWorkflow =
+	| { mode: "single"; delegations: [Delegation] }
+	| { mode: "parallel"; delegations: Delegation[] }
+	| { mode: "chain"; delegations: Delegation[] };
+export type ParsedDelegateTask = ({ mode: "direct"; workflow: ParsedWorkflow } | { mode: "isolated"; request: ExecuteRequest }) & { dryRun: boolean };
+
+type DirectInput = Static<typeof DirectWorkflowSchema>;
+const DELEGATION_KEYS = ["role", "name", "task", "access", "paths", "continueFrom", "kind", "model", "modelClass"] as const;
+
+function text(value: string, path: string): string {
+	const normalized = value.trim();
+	if (!normalized || value.includes("\0")) throw new Error(`${path} must be non-empty text without NUL.`);
+	return normalized;
+}
+
+function normalizeTaskName(value: string, path: string): string {
+	const normalized = value.trim();
+	if (!normalized) throw new Error(`${path} must be non-empty text.`);
+	return normalized;
+}
+
+function normalizePaths(value: Static<typeof DelegationSchema>, path: string): string[] | undefined {
+	if (value.paths === undefined) return;
+	if (value.access !== "write") throw new Error(`${path}.paths requires access "write"; it declares where a write task may change files.`);
+	return value.paths.map((glob, index) => {
+		const normalized = text(glob, `${path}.paths[${index}]`);
+		if (normalized.startsWith("/") || normalized.split("/").includes("..")) throw new Error(`${path}.paths[${index}] must be a repo-relative glob without .. segments.`);
+		return normalized;
+	});
+}
+
+function normalizeDelegation(value: Static<typeof DelegationSchema>, path: string): Delegation {
+	const paths = normalizePaths(value, path);
+	return {
+		role: text(value.role, `${path}.role`),
+		name: normalizeTaskName(value.name, `${path}.name`),
+		task: text(value.task, `${path}.task`),
+		access: value.access,
+		...(paths === undefined ? {} : { paths }),
+		...(value.continueFrom === undefined ? {} : { continueFrom: value.continueFrom }),
+		kind: "text",
+		...(value.model === undefined ? {} : { model: text(value.model, `${path}.model`) }),
+		...(value.modelClass === undefined ? {} : { modelClass: value.modelClass }),
+	};
+}
+
+function hasDelegation(value: DirectInput): value is DirectInput & Static<typeof DelegationSchema> {
+	return Object.hasOwn(value, "role") && Object.hasOwn(value, "name") && Object.hasOwn(value, "task");
+}
+
+function requireAccess(value: unknown, path: string): void {
+	if (!value || typeof value !== "object") return; // The schema rejects non-object tasks.
+	const { access } = value as { access?: unknown };
+	if (!DIRECT_ACCESS.some((candidate) => candidate === access)) {
+		throw new Error(`${path}.access must be ${DIRECT_ACCESS.map((candidate) => JSON.stringify(candidate)).join(" or ")}${access === undefined ? " (missing)" : `, got ${JSON.stringify(access)}`}. ${ACCESS_GUIDANCE}`);
+	}
+}
+
+function workflowMode(value: unknown): WorkflowMode | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const single = DELEGATION_KEYS.some((key) => Object.hasOwn(value, key));
+	const parallel = Object.hasOwn(value, "tasks");
+	const chain = Object.hasOwn(value, "chain");
+	if (Number(single) + Number(parallel) + Number(chain) !== 1) throw new Error("direct workflow must select exactly one of single, tasks, or chain.");
+	return single ? "single" : parallel ? "parallel" : "chain";
+}
+
+export function parseWorkflow(value: unknown): ParsedWorkflow {
+	const mode = workflowMode(value);
+	if (mode === "single") requireAccess(value, "workflow");
+	else if (mode) {
+		const items = (value as Record<string, unknown>)[mode === "parallel" ? "tasks" : "chain"];
+		if (Array.isArray(items)) items.forEach((item, index) => requireAccess(item, `${mode === "parallel" ? "tasks" : "chain"}[${index}]`));
+	}
+	if (!Check(DirectWorkflowSchema, value)) {
+		const issue = Errors(DirectWorkflowSchema, value)[0];
+		throw new Error(`direct workflow must match the declared tool schema${issue ? ` at ${issue.instancePath || "/"}: ${issue.message}` : ""}. Direct mode returns task answers without checked integration; use mode isolated for changesets.`);
+	}
+	if (!mode) throw new Error("direct workflow must select exactly one of single, tasks, or chain.");
+	const input = value as DirectInput;
+	if (mode === "single" && !hasDelegation(input)) throw new Error("direct workflow requires role, name, task, and access.");
+	const workflow: ParsedWorkflow = mode === "single" ? { mode, delegations: [normalizeDelegation(input as Static<typeof DelegationSchema>, "workflow")] }
+		: mode === "parallel" ? { mode, delegations: input.tasks!.map((item, index) => normalizeDelegation(item, `tasks[${index}]`)) }
+		: { mode, delegations: input.chain!.map((item, index) => normalizeDelegation(item, `chain[${index}]`)) };
+	const continued = workflow.delegations.flatMap(({ continueFrom }) => continueFrom === undefined ? [] : [continueFrom]);
+	if (new Set(continued).size !== continued.length) throw new Error("A direct request may continue each worker at most once.");
+	return workflow;
+}
+
+/** A direct request is a writer request when any task declares write access. */
+export const writesCheckout = (workflow: ParsedWorkflow): boolean => workflow.delegations.some(({ access }) => access === "write");
+
+/** `dryRun` is a tool-call option, not part of the direct workflow or the durable isolated request. */
+export function parseDelegateTask(value: unknown): ParsedDelegateTask {
+	let dryRun = false;
+	if (value && typeof value === "object" && !Array.isArray(value) && Object.hasOwn(value, "dryRun")) {
+		const { dryRun: option, ...rest } = value as Record<string, unknown>;
+		if (typeof option !== "boolean") throw new Error(`delegate_task dryRun must be a boolean, got ${JSON.stringify(option)}.`);
+		dryRun = option;
+		value = rest;
+	}
+	if (value && typeof value === "object" && !Array.isArray(value) && (value as { mode?: unknown }).mode === "isolated") {
+		return { mode: "isolated", request: parseExecuteRequest(value), dryRun };
+	}
+	return { mode: "direct", workflow: parseWorkflow(value), dryRun };
+}
+
+/** Main's checkout state: HEAD plus porcelain status and content identity of each dirty path. */
+export type CheckoutSnapshot = { head?: string; entries: Map<string, string>; fingerprint: string };
+
+export type ChangeReport = {
+	/** Set when HEAD moved to a commit that does not descend from the launch HEAD. */
+	headMove?: string;
+	commits: Array<{ oid: string; subject: string }>;
+	omittedCommits: number;
+	paths: Array<{ path: string; outside?: true }>;
+	omittedPaths: number;
+};
+
+export type CheckoutNote =
+	| { kind: "changes"; report: ChangeReport }
+	| { kind: "stale" }
+	| { kind: "unavailable"; check: "change report" | "stale-read check"; reason: string };
+
+export const CHANGE_REPORT_LIMITS = { commits: 10, paths: 20, subject: 120, reason: 500 } as const;
+
+async function contentIdentity(path: string): Promise<string> {
+	const stats = await lstat(path).catch(() => undefined);
+	if (!stats) return "absent";
+	if (stats.isSymbolicLink()) return `link ${await readlink(path)}`;
+	if (!stats.isFile()) return "other";
+	const hash = createHash("sha256");
+	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	return hash.digest("hex");
+}
+
+// Background snapshots must not take index.lock while Main or a worker writes.
+async function git(cwd: string, args: string[], codes = [0]) {
+	const result = await runGit(["--no-optional-locks", ...args], cwd);
+	if (!codes.includes(result.code)) throw new Error(`git ${args[0]} exited ${result.code}: ${result.stderr.trim() || "no diagnostic"}`);
+	return result;
+}
+
+/** Snapshot the checkout that contains `cwd`; undefined outside a Git repository. Other Git failures throw. */
+export async function snapshotCheckout(cwd: string): Promise<CheckoutSnapshot | undefined> {
+	const top = await runGit(["--no-optional-locks", "rev-parse", "--show-toplevel"], cwd);
+	if (top.code !== 0 && /not a git repository/i.test(top.stderr)) return undefined;
+	const root = top.stdout.trim();
+	if (top.code !== 0 || !root) throw new Error(`git rev-parse exited ${top.code}: ${top.stderr.trim() || "no diagnostic"}`);
+	const head = (await git(root, ["rev-parse", "--verify", "--quiet", "HEAD"], [0, 1])).stdout.trim() || undefined;
+	// Porcelain paths are repository-relative; an index or worktree rename or copy lists its source after the destination.
+	const fields = (await git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"])).stdout.split("\0");
+	const entries = new Map<string, string>();
+	for (let index = 0; index < fields.length; index++) {
+		const field = fields[index]!;
+		if (!field) continue;
+		const status = field.slice(0, 2);
+		entries.set(field.slice(3), status);
+		if (/[RC]/.test(status)) entries.set(fields[++index]!, status);
+	}
+	// Status alone misses a further edit to a path that was already dirty.
+	for (const [path, status] of entries) entries.set(path, `${status} ${await contentIdentity(posix.join(root, path))}`);
+	const fingerprint = createHash("sha256").update(JSON.stringify([head ?? null, [...entries].sort()])).digest("hex");
+	return { ...(head === undefined ? {} : { head }), entries, fingerprint };
+}
+
+/** Commits and changed paths between two snapshots of the same checkout. */
+export async function reportCheckoutChanges(cwd: string, before: CheckoutSnapshot, after: CheckoutSnapshot, declared?: readonly string[]): Promise<ChangeReport> {
+	const changed = new Set([...before.entries.keys(), ...after.entries.keys()].filter((path) => before.entries.get(path) !== after.entries.get(path)));
+	const report: ChangeReport = { commits: [], omittedCommits: 0, paths: [], omittedPaths: 0 };
+	const short = (oid: string) => oid.slice(0, 12);
+	if (before.head !== after.head && after.head === undefined) report.headMove = `HEAD moved from ${short(before.head!)} to an unborn branch`;
+	else if (before.head !== after.head) {
+		const range = before.head === undefined ? [after.head!] : [`${before.head}..${after.head}`];
+		const total = Number((await git(cwd, ["rev-list", "--count", ...range, "--"])).stdout.trim());
+		const log = (await git(cwd, ["log", "--no-show-signature", `--max-count=${CHANGE_REPORT_LIMITS.commits}`, "--format=%h%x00%s", ...range, "--"])).stdout;
+		report.commits = log.split("\n").filter(Boolean).map((line) => {
+			const [oid, subject = ""] = line.split("\0");
+			return { oid: oid!, subject: Array.from(subject).slice(0, CHANGE_REPORT_LIMITS.subject).join("") };
+		});
+		report.omittedCommits = Math.max(0, total - report.commits.length);
+		const names = before.head === undefined
+			? await git(cwd, ["ls-tree", "-r", "--name-only", "-z", "--full-tree", after.head!])
+			: await git(cwd, ["diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--no-textconv", before.head, after.head!, "--"]);
+		for (const path of names.stdout.split("\0")) if (path) changed.add(path);
+		if (before.head !== undefined && (await git(cwd, ["merge-base", "--is-ancestor", before.head, after.head!], [0, 1])).code === 1) {
+			report.headMove = `HEAD moved from ${short(before.head)} to ${short(after.head!)}, which does not descend from it`;
+		}
+	}
+	const outside = (path: string) => declared !== undefined && !declared.some((glob) => posix.matchesGlob(path, glob));
+	// Outside paths come first so the cap never hides them.
+	const paths = [...changed].sort().map((path) => outside(path) ? { path, outside: true as const } : { path })
+		.sort((left, right) => Number(Boolean(right.outside)) - Number(Boolean(left.outside)));
+	report.paths = paths.slice(0, CHANGE_REPORT_LIMITS.paths);
+	report.omittedPaths = paths.length - report.paths.length;
+	return report;
+}
+
+/** Compare a task's launch snapshot with the checkout at its terminal outcome. Failures become a note, never a task failure. */
+export async function checkoutNote(cwd: string, before: CheckoutSnapshot | Error | undefined, write: boolean, declared?: readonly string[]): Promise<CheckoutNote | undefined> {
+	try {
+		if (before instanceof Error) throw before;
+		if (before === undefined) return;
+		const after = await snapshotCheckout(cwd);
+		if (after === undefined) throw new Error("the checkout is no longer a Git repository");
+		if (write) return { kind: "changes", report: await reportCheckoutChanges(cwd, before, after, declared) };
+		return after.fingerprint === before.fingerprint ? undefined : { kind: "stale" };
+	} catch (error) {
+		return { kind: "unavailable", check: write ? "change report" : "stale-read check", reason: Array.from(error instanceof Error ? error.message : String(error)).slice(0, CHANGE_REPORT_LIMITS.reason).join("") };
+	}
+}
+
+export type WorkflowEntry = { id: string; index: number; delegation: Delegation };
+export function identifyWorkflowEntries(toolCallId: string, workflow: ParsedWorkflow): WorkflowEntry[] {
+	return workflow.delegations.map((delegation, index) => ({ id: `${toolCallId}:${workflow.mode}:${index}`, index, delegation }));
+}
+
+export type DelegationRunner = (entry: WorkflowEntry) => string | Promise<string>;
+
+async function runEntry(entry: WorkflowEntry, run: DelegationRunner): Promise<string | undefined> {
+	try {
+		return await run(entry);
+	} catch {
+		return undefined;
+	}
+}
+
+export async function runForegroundWorkflow(
+	mode: WorkflowMode,
+	entries: readonly WorkflowEntry[],
+	run: DelegationRunner,
+	signal?: AbortSignal,
+): Promise<void> {
+	signal?.throwIfAborted();
+	if (mode === "single" || mode === "parallel") {
+		await Promise.all(entries.map((entry) => runEntry(entry, run)));
+		signal?.throwIfAborted();
+		return;
+	}
+	let previous = "";
+	for (const entry of entries) {
+		const selected = {
+			...entry,
+			delegation: { ...entry.delegation, task: entry.delegation.task.replaceAll("{previous}", () => previous) },
+		};
+		const output = await runEntry(selected, run);
+		signal?.throwIfAborted();
+		if (output === undefined) break;
+		previous = output;
+	}
+}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@hcflabs/pi-subagent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "27.10.7",
+  "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "subagent",
+    "delegation"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "LICENSE",
+    "dist",
+    "extensions",
+    "docs",
+    "examples",
+    "prompts",
+    "example.png",
+    "README.md",
+    "CONTEXT.md",
+    "skills"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "pretypecheck": "npm run build",
+    "test": "npm run build && node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck src/*.ts extensions/*.ts test/*.test.ts",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-tui": "^1.3.0",
+    "typebox": "^1.3.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hcflabs/pi-harness.git",
+    "directory": "extensions/pi-subagent"
+  },
+  "bugs": {
+    "url": "https://github.com/hcflabs/pi-harness/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/subagent.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "image": "https://raw.githubusercontent.com/hcflabs/pi-harness/main/extensions/pi-subagent/example.png"
+  },
+  "dependencies": {
+    "@hcflabs/pi-config-store": "^4.0.0",
+    "@hcflabs/pi-herdr": "^0.5.0",
+    "@hcflabs/pi-multi-codex": "^3.0.0",
+    "@hcflabs/pi-process": "^0.2.0",
+    "@hcflabs/pi-task-models": "^9.0.0",
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
+    "@types/proper-lockfile": "^4.1.4"
+  }
+}

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.

package/skills/pi-subagent/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: pi-subagent
+description: Delegate bounded direct work or run durable checked isolated task graphs.
+---
+
+# Choose and authorize delegation
+
+Use this Skill only from Main.
+
+Record the requested outcome, allowed scope and exclusions, local delegation/check/review/integration permission, and any external-action permission before substantial work. A clear small request can supply this authorization directly. Ask again only for a material scope or contract change, a missing decision or authorization, a user-owned conflict, or a consequential action outside that scope.
+
+Keep trivial, mechanically verifiable work in Main. Choose the user-requested mode when one is explicit. Otherwise:
+
+- Use `mode: direct` for bounded research, analysis, review, or explicitly authorized shared-checkout writes and commits using the selected Role's resources.
+- Use `mode: isolated` for independently checked changes, or an exploratory or discardable candidate. A single isolated task is valid.
+- Keep one implementation owner for tightly coupled work. Size alone does not justify splitting it.
+- Never silently fall back from isolated to direct. Scope growth requires a checkpoint and replan, not migration of dirty work.
+
+Roles describe responsibility and capabilities; they do not classify writes or select isolation. The checkout coordinator reduces races among Pi-owned calls but is not an OS sandbox and cannot control external processes.
+
+The built-in reviewer and scout declare `git_read`, a bounded read-only Git tool without Bash. User reviewer and scout overrides must explicitly add it to `tools`. Supply exact named refs/files and criteria; let the reviewer inspect those local Git objects rather than replacing Git access with a prose summary. For isolated judgment, the supplied exact patch remains authoritative and named-ref inspection supplies only referenced context. Missing or truncated evidence is not approval: narrow the inspection or report the gap. Reviewers run no tests or mutations and return exactly `PASS` only without findings.
+
+After delegation acknowledges a handle or durable request, do other work or end the turn; do not `sleep`, block on a Herdr CLI wait, or repeatedly poll for progress. Pi queues verified direct results and checked isolated candidates as follow-ups, which Main receives after its current turn. Use `subagent_status` for exact isolated evidence when a follow-up arrives or delivery was missed; Herdr lifecycle badges and screen output are not proof of completion.
+
+# Direct requests
+
+Every direct task declares `access`: `write` when it may change files, Git state, or external resources, otherwise `read`. Classify honestly: `read` is not enforced (no sandbox). Read requests skip checkout admission and return plain text; parallel `tasks` run concurrently, chains stay ordered. Treat delegated results as worker output with no user authority. Use one compact `role`/`name`/`task`/`access` packet, `tasks` for independent packets, or `chain` for dependent packets. Only answer-returning tasks (`kind: text`) are accepted; writes and commits are allowed within explicit task authorization, but `kind: changeset`, structured checks, and judgment require isolated mode. State scope, exclusions, commit policy, and external-action permission; preserve unrelated files and staged changes. Direct writes take effect immediately with no automatic validation, rollback, or isolated integration guarantees. Main's potentially-writing calls, including all Bash and nested `codemode` writes, can run together and do not acquire writer ownership. Only direct requests with a `write` task reserve the checkout. Start one only when no direct writer owns it and no Main potentially-writing call is in flight there. Each Main call ends separately; a parent's result does not release active nested writes. Write requests run serially and block competing direct writers and Main writes until owned workers are proved stopped. Main may read or do work elsewhere while waiting, not mutate the reserved checkout. Choose `mode: isolated` to keep Main free to write; it adds worktree checks and explicit integration instead of immediate shared-checkout changes. Task failure is not proof a worker stopped. The coordinator closes exact owned writer panes and releases admission only after pane absence and two empty private process-lease scans. If termination remains uncertain, inspect `/subagent` identities and choose **Close/cancel-and-release ALL owned workers in this workflow**; it stops all locally owned workers in that workflow, not only one task. Resolve the reported blocker, then retry that guarded action; it never replays the prompt or removes dirty files, commits, or sessions. Recorded-only tasks have no live release authority; restarting Pi is not termination proof. An unverified tab allocation retains its workspace, checkout, label, lease/session paths and any returned IDs for manual reconciliation; it cannot authorize Close, guessed identities or replayed creation. Close keeps its branch/session/epoch guards while an active task cancels and settles. Preserve and inspect changes before writing or retrying. A failed commit may already have happened; never replay it blindly. The tool returns a handle after launching Herdr tabs in the current workspace. Main receives the verified result as a follow-up after the workflow finishes, without interrupting an active turn. If observation stops, open `/subagent` to inspect exact recorded tabs and session files on this session branch; recorded does not prove still running.
+
+To build on a finished direct worker, add `continueFrom` with its reference (such as `D7.1`) and the same `role`. The worker resumes its saved Pi session in a new tab, so continue it for follow-up questions, corrections, or the next step on the same evidence. Start a fresh task for unrelated work, a different Role, or when the earlier context is stale, wrong, or large. Continuation fails before launch for an unknown reference, a different Role, a worker still owned by an active task, a missing or oversized session, an unfinished last turn, or a busy old agent; do not retry it blindly. The user can stop one running worker of a read-only workflow with **Stop this worker** in `/subagent`; that entry fails with `Stopped by user from /subagent` and its siblings continue.
+
+# Isolated requests
+
+Give the request a unique ID and goal. Give each task a unique ID, kind, Role, model class, bounded requirements, deliverable, `dependsOn`, and `contextFrom`. Changesets require focused task checks, and a graph containing changesets requires final checks. The root must have a `package.json` test script; `pnpm test` is added to final checks if missing and runs against the combined tip before Main promotion. Text context may name only completed text tasks, preserves declared order, and implies a scheduling dependency; do not repeat an edge in `dependsOn` and `contextFrom`.
+
+Every changeset becomes ready automatically after preliminary checks pass. While a locally owned changeset task is actively working, the user may open `/subagent` to queue bounded same-worker revisions or withdraw all still-pending instructions into the native editor and submit one replacement. Cancellation after withdrawal leaves the originals removed; already-claimed instructions cannot be recalled. Each revision must produce a new clean commit and rerun preliminary checks. If a worker's turn ends with uncommitted changes, the runner sends it one commit reminder per attempt; this uses no correction, and a worktree still dirty afterwards needs attention. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for sibling workers. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.
+
+A ready candidate does not integrate automatically. Each checked worker triggers a follow-up while its siblings continue; inspect `subagent_status` and immediately use `subagent_stage` with the exact `generation`, `taskId`, `attempt`, candidate `tip`, and `expectedTip` to select and merge it into the owned integration checkout. Stage and resolve are available during the active wave; wait for the wave to settle before rejecting or revising. Resolve conflicts in the integration checkout and verify with `resolve`; never edit Main to resolve them. For dependents, `subagent_integrate advance` acknowledges a durable background wave, then reports checked candidates as they finish. When selected work is staged and the wave settles, use `subagent_integrate validate` on the exact `combinedTip`: it acknowledges saved intent, runs full root checks and optional final judgment in the session-owned background, then sends a follow-up. Acknowledgement is not passing evidence; `promote` requires passing evidence and unchanged Main. One Main-authored committed correction to a definitively failed combined validation can be recorded with `correct`, then revalidated. Only proven promotion triggers selected-worker termination and verified cleanup. Failures, ambiguity, conflicts, interruption, child-limit exhaustion, or Main drift retain work and never waive checks or identity guards. The extension never pushes, opens a pull request, publishes, or deploys.
+
+After a coordinator interruption in the canonical repository, ask the user to run `/subagent recover` once; if another productive run holds the lease, wait and run it again. It acquires the productive lease, classifies interrupted work, preserves invalid files and retained work, and sends Main one follow-up with blockers and next actions. A live productive lease is read-only and cannot be taken over. Recovery never replays prompts, merges, promotion, or cleanup. For leftover merged worker or integration checkouts, ask the user to run `/subagent prune`; it removes only reviewed, confirmed, merged, clean, unowned items. Use `subagent_status` to inspect exact durable state without mutation, including candidate identities, generations, and retained resources. `subagent_resume` handles only the reported retry/verify/finalize continuation; it cannot replace Main's stage/integrate decisions or reset policy/corrections. For a retry that sends a same-worker correction, pass `instruction` to name the exact fixes, including the review or check findings the worker must address; the correction prompt carries only a short saved failure. Follow-ups show a short preview of a failed review verdict; `subagent_status` returns it in full. `subagent_stage reject` or `revise` freezes a generation containing the candidate and invalidates dependent attempts; restage chosen work in a new generation. If Main advances cleanly before promotion, use `subagent_integrate refresh` with exact old/new Main and combined-tip identities; restage immutable candidates into the new generation and rerun combined validation. Dirty or divergent Main blocks refresh. For interrupted validation, prove old coordinator/check processes stopped, then guarded `reconcile` classifies the exact generation; never resume a live lease. A `validation_failed` generation without checks, review, or a prior combined correction can `refresh` with identical `expectedMain`/`newMain`, the old exact combined `expectedTip`, and the next generation number. Main and the retained integration tip must be exact and clean. Restage immutable candidates explicitly and rerun all final gates in the new checkout; never replay old uncertain checks, infer passing evidence, or reset correction allowances. At most two unreleased integration worktrees may coexist. Rejected candidates and superseded generations remain retained until Main explicitly calls `subagent_integrate release` with the exact generation and tip; for a rejected worker include its task ID and attempt after releasing all generations using it. Dirty/conflicted or unproved resources block release without force deletion. Impossible fresh dependent work after rejection needs a new request. `subagent_abort` cannot discard retained candidates or integration generations; release them first. For workers without candidates, abort cleans only proven unchanged, clean owned resources. If cleanup is deferred or blocked, inspect status and repeat abort after resolving the blocker. Dirty or committed work and uncertain allocations remain for manual recovery. To delete owned isolated worktrees, ask the user to run `/subagent` and choose **Close and delete worktrees (discard work)**; agents cannot trigger it. Old v4 state is rejected (current state is v5), not migrated. Status, abort, process I/O, termination, and verified post-promotion cleanup keep finite safety budgets.
+
+All launches use the global policy in `config/pi-subagent/config.json`: productive concurrency, per-child turns/tokens, and idle timeout. Ephemeral children also have a hard runtime limit; isolated requests have a correction cap. Productive requests have no whole-run wall-clock deadline. Request fields cannot replenish or override limits.