@henryqw/pi-subagent 22.0.1 → 22.2.0

package/extensions/subagent.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, Text, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import { type Component, Text, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { availableTaskModels, loadTaskModelsConfig, modelReference, registerModelTask, resolveAvailableModel, type ResolvedTaskRoute, taskThinkingLevels } from "@henryqw/pi-task-models";
 import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, DELEGATE_TASK, formatDuration, loadRoles, prepareRoleLaunch, ROLE_TOOL_POLICY_FLAG, type EphemeralSubagentTimeout, type Role } from "@henryqw/pi-subagent";
 import { DEFAULT_EXECUTION_POLICY, DEFAULT_TIMEOUT_CONFIG, readSubagentConfig, resolveExecutionPolicy, type EffectiveExecutionPolicy } from "./config.ts";
@@ -13,10 +13,9 @@ import { DelegateTaskSchema, identifyWorkflowEntries, parseDelegateTask, runFore
 import { createDirectHerdr, type DirectHandle, type DirectTab } from "../dist/direct-herdr.js";
 import { materializeTransientLaunch } from "../dist/launch-runtime.js";
 const WIDGET_KEY = "subagent-status";
-const WIDGET_INTERVAL_MS = 80;
+const WIDGET_INTERVAL_MS = 1_000;
 const MAX_WIDGET_ITEMS = 8;
 const MAX_WIDGET_LINES = 6;
-const MAX_WIDGET_GROUP_ROWS = 3;
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 type TimeoutPolicy = EphemeralSubagentTimeout;
@@ -30,6 +29,7 @@ type WidgetItem = {
 	startedAt: number;
 	status: WidgetStatus;
 	finishedAt?: number;
+	tokens?: number;
 };
 
 function roleBadge(role: string): string {
@@ -55,15 +55,8 @@ function statusLabel(status: WidgetStatus): string {
 	}
 }
 
-function activityLabel(item: WidgetItem): string {
-	if (item.status === "success") return "Done";
-	if (item.status === "failure") return "Failed";
-	if (item.status === "aborted") return "Stopped";
-	return "working…";
-}
-
-function activityMetrics(item: WidgetItem, now: number): string {
-	return `${item.model}·${item.thinkingLevel} · ${formatDuration((item.finishedAt ?? now) - item.startedAt)}`;
+function tokenLabel(tokens: number | undefined): string {
+	return tokens === undefined ? "— tok" : `${tokens < 1_000 ? tokens : `${(tokens / 1_000).toFixed(1).replace(/\.0$/, "")}k`} tok`;
 }
 
 function renderWidgetRows(
@@ -73,36 +66,26 @@ function renderWidgetRows(
 	spinnerIndex: number,
 	theme: Theme,
 ): string[] {
-	const ordered = [...items.filter(({ status }) => status === "working"), ...items.filter(({ status }) => status !== "working")];
-	if (!ordered.length) return [];
-	const groups = new Map<string, { name: string; items: WidgetItem[] }>();
-	for (const item of ordered) {
-		const group = groups.get(item.taskId);
-		if (group) group.items.push(item);
-		else groups.set(item.taskId, { name: item.name, items: [item] });
-	}
-	const maxVisibleLines = ordered.length + groups.size > MAX_WIDGET_LINES ? MAX_WIDGET_LINES - 1 : MAX_WIDGET_LINES;
-	const workingGroups = [...groups.values()].filter(({ items }) => items.some(({ status }) => status === "working"));
-	const visibleWorkingGroups = new Set(workingGroups.slice(0, Math.floor(maxVisibleLines / 2)));
-	let remainingWorkingGroups = visibleWorkingGroups.size;
-	const visible = new Set<WidgetItem>();
-	const lines: string[] = [];
-	for (const group of groups.values()) {
-		const working = group.items.some(({ status }) => status === "working");
-		if (working && !visibleWorkingGroups.has(group)) continue;
-		const reservedLines = working ? --remainingWorkingGroups * 2 : 0;
-		const childCount = Math.min(MAX_WIDGET_GROUP_ROWS, group.items.length, maxVisibleLines - lines.length - reservedLines - 1);
-		if (childCount < 1) continue;
-		lines.push(truncateToWidth(theme.fg("text", group.name), width));
-		for (const item of group.items.slice(0, childCount)) {
-			visible.add(item);
-			lines.push(truncateToWidth(
-				`  ${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} ${theme.fg("text", activityLabel(item))} · ${theme.fg("muted", activityMetrics(item, now))}`,
-				width,
-			));
+	const ordered = [...items].sort((a, b) =>
+		(a.status === "failure" ? 0 : a.status === "working" ? 1 : 2)
+		- (b.status === "failure" ? 0 : b.status === "working" ? 1 : 2));
+	const visible = ordered.slice(0, ordered.length > MAX_WIDGET_LINES ? MAX_WIDGET_LINES - 1 : MAX_WIDGET_LINES);
+	const lines = visible.map((item) => {
+		const prefix = `${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", `D ${item.role}`)} ${item.status === "working" ? "" : `${statusLabel(item.status)} · `}`;
+		const metrics = [
+			`${item.model}/${item.thinkingLevel}`,
+			tokenLabel(item.tokens),
+			formatDuration((item.finishedAt ?? now) - item.startedAt),
+		];
+		while (metrics.length && width - visibleWidth(prefix) - visibleWidth(` · ${metrics.join(" · ")}`) < 8) {
+			if (metrics.length === 2) metrics.shift(); // Preserve measured tokens ahead of route details.
+			else metrics.pop();
 		}
-	}
-	const hidden = ordered.filter((item) => !visible.has(item));
+		const suffix = metrics.length ? ` · ${theme.fg("muted", metrics.join(" · "))}` : "";
+		const name = truncateToWidth(theme.fg("text", item.name), Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix)));
+		return truncateToWidth(`${prefix}${name}${suffix}`, width);
+	});
+	const hidden = ordered.slice(visible.length);
 	if (hidden.length) {
 		const counts: Record<WidgetStatus, number> = { working: 0, success: 0, failure: 0, aborted: 0 };
 		for (const { status } of hidden) counts[status] += 1;
@@ -177,6 +160,8 @@ export default function subagentExtension(
 		].join("\n"), outputPad, 0);
 	});
 	const widgetItems = new Map<string, WidgetItem>();
+	const tokenHandles = new Map<string, DirectHandle>();
+	const samplingTokens = new Set<string>();
 	const loadedConfig = readSubagentConfig();
 	let initialPolicy: EffectiveExecutionPolicy;
 	try {
@@ -243,7 +228,51 @@ export default function subagentExtension(
 			return [...grouped.values()];
 		},
 		isolated: (cwd) => isolatedSurface.inventory(cwd),
-		inspect: (root, id) => isolatedSurface.inspect(root, id),
+		recover: (cwd) => isolatedSurface.recover(cwd),
+		async inspectInTab(root, id, ctx, current) {
+			const notices = await isolatedSurface.inspect(root, id);
+			if (!current()) throw new Error("Session or branch changed before status inspection.");
+			const snapshot = notices.join("\n");
+			if (Buffer.byteLength(snapshot, "utf8") > 32_000) throw new Error("Status exceeds the 32 KiB inspection limit; use subagent_status for exact evidence.");
+			const role = loadRoles().find((candidate) => candidate.name === "scout");
+			if (!role || roleCanWrite(role)) throw new Error("Status inspection requires a configured read-only scout Role.");
+			const prepared = prepareRoleLaunch(pi, ctx, { role, task: DELEGATE_TASK, modelClass: "fast" });
+			const herdr = createDirectHerdr(pi, ctx.cwd, currentPolicy().childIdleMs);
+			const controller = new AbortController();
+			const taskId = `inspect-${id}-${randomUUID()}`;
+			const handles: DirectHandle[] = [];
+			const tabs: DirectTabRecord[] = [];
+			let resolveSettled!: () => void;
+			const settled = new Promise<void>((resolve) => { resolveSettled = resolve; });
+			directTasks.set(taskId, { controller, settled, handles, tabs });
+			try {
+				const transient = await materializeTransientLaunch({ launch: prepared, prompt: prepared.systemPrompt,
+					promptArgIndex: prepared.promptArgIndex }, controller.signal);
+				let handle: DirectHandle;
+				try {
+					handle = await herdr.start(
+						{ ...prepared, args: [...transient.launch.args] }, `i-${randomUUID().replaceAll("-", "").slice(0, 24)}`,
+						`Inspect ${id}`, `Analyze this saved, read-only status snapshot for request ${id}. Summarize blockers and safe next decisions; do not infer missing evidence or mutate resources. The subagent_status tool in Main remains authoritative for exact action identities.\n\n${snapshot}`,
+						controller.signal, (tab) => {
+							const record = { taskId, entryId: id, ...tab };
+							pi.appendEntry(DIRECT_TAB_TYPE, record);
+							tabs.push(record);
+						});
+				} catch (error) {
+					throw new Error(`${error instanceof Error ? error.message : String(error)}. Inspection Role prompt retained at ${transient.launch.args[prepared.promptArgIndex + 1]} after uncertain start.`, { cause: error });
+				}
+				handles.push(handle);
+				await transient.cleanup();
+				if (!current() || controller.signal.aborted) {
+					await handle.cancel();
+					throw new Error(`Session changed during inspection launch; inspect Herdr tab ${handle.tabId}.`);
+				}
+				return { tabId: handle.tabId, name: handle.name, sessionFile: handle.sessionFile };
+			} finally {
+				directTasks.delete(taskId);
+				resolveSettled();
+			}
+		},
 		canFollowup: (root, id, task) => isolatedSurface.canFollowup(root, id, task),
 		enqueue: (root, id, task, text, current) => isolatedSurface.enqueue(root, id, task, text, current),
 		drain: (root, id, task, current) => isolatedSurface.drain(root, id, task, current),
@@ -252,6 +281,7 @@ export default function subagentExtension(
 	let widgetInstalled = false;
 	let widgetTimer: ReturnType<typeof setInterval> | undefined;
 	let spinnerIndex = 0;
+	let widgetTicks = 0;
 	let activeTui: TUI | undefined;
 	const stopWidgetTimer = () => {
 		if (!widgetTimer) return;
@@ -266,6 +296,19 @@ export default function subagentExtension(
 		widgetTimer = setInterval(() => {
 			spinnerIndex = (spinnerIndex + 1) % SPINNER_FRAMES.length;
 			requestWidgetRender();
+			if (++widgetTicks % 2 !== 0) return;
+			for (const [id, handle] of tokenHandles) {
+				if (samplingTokens.has(id)) continue;
+				samplingTokens.add(id);
+				void handle.usageTokens().then((tokens) => {
+					const item = widgetItems.get(id);
+					if (tokens !== undefined && item?.status === "working" && tokenHandles.get(id) === handle) {
+						item.tokens = tokens;
+						requestWidgetRender();
+					}
+				}).catch(() => { /* Usage is optional; never interrupt work for telemetry. */ })
+					.finally(() => samplingTokens.delete(id));
+			}
 		}, WIDGET_INTERVAL_MS);
 		widgetTimer.unref();
 	};
@@ -316,6 +359,7 @@ export default function subagentExtension(
 	const finishWidgetItem = (id: string, status: Exclude<WidgetStatus, "working">) => {
 		const item = widgetItems.get(id);
 		if (!item) return;
+		tokenHandles.delete(id);
 		item.status = status;
 		item.finishedAt = Date.now();
 		if (![...widgetItems.values()].some(({ status }) => status === "working")) stopWidgetTimer();
@@ -357,6 +401,8 @@ export default function subagentExtension(
 	pi.on("session_shutdown", async (_event, ctx) => {
 		stopWidgetTimer();
 		widgetItems.clear();
+		tokenHandles.clear();
+		samplingTokens.clear();
 		activeTui = undefined;
 		widgetInstalled = false;
 		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
@@ -506,6 +552,7 @@ export default function subagentExtension(
 				}
 				await transient.cleanup();
 				handles.push(handle);
+				if (widgetItems.has(entry.id)) tokenHandles.set(entry.id, handle);
 				return handle;
 			};
 			// The first tab is verified before returning a handle; subsequent independent
@@ -538,12 +585,16 @@ export default function subagentExtension(
 						active++;
 						return () => { active--; queue.shift()?.(); };
 					};
-					await runForegroundWorkflow(toolCallId, workflow, async (entry) => {
+					await runForegroundWorkflow(workflow.mode, entries, async (entry) => {
 						const release = await permit();
 						try {
 							controller.signal.throwIfAborted();
 							const handle = entry.index === 0 ? first : await launch(entry, controller.signal);
 							const answer = await handle.answer(Math.floor(40 * 1024 / entries.length));
+							try {
+								const tokens = await handle.usageTokens();
+								if (tokens !== undefined && widgetItems.has(entry.id)) widgetItems.get(entry.id)!.tokens = tokens;
+							} catch { /* Optional telemetry. */ }
 							const base = states.get(entry.id)!;
 							states.set(entry.id, { id: base.id, index: base.index, name: base.name, role: base.role,
 								...(base.model ? { model: base.model } : {}), ...(base.thinkingLevel ? { thinkingLevel: base.thinkingLevel } : {}),

package/extensions/workflow.ts

@@ -4,10 +4,17 @@ import { PROFILE_NAMES } from "@henryqw/pi-task-models";
 import { Type, type Static } from "typebox";
 import { Check, Errors } from "typebox/value";
 import { ExecuteRequestSchema, parseExecuteRequest, type ExecuteRequest } from "../dist/schema.js";
-import { TaskNameSchema, normalizeTaskName } from "./task-name.ts";
 
 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" });
@@ -55,6 +62,12 @@ function text(value: string, path: string): string {
 	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 normalizeDelegation(value: Static<typeof DelegationSchema>, path: string): Delegation {
 	return {
 		role: text(value.role, `${path}.role`),
@@ -118,19 +131,18 @@ async function runEntry(entry: WorkflowEntry, run: DelegationRunner): Promise<st
 }
 
 export async function runForegroundWorkflow(
-	toolCallId: string,
-	workflow: ParsedWorkflow,
+	mode: WorkflowMode,
+	entries: readonly WorkflowEntry[],
 	run: DelegationRunner,
 	signal?: AbortSignal,
 ): Promise<void> {
 	signal?.throwIfAborted();
-	const entries = identifyWorkflowEntries(toolCallId, workflow);
-	if (workflow.mode === "single") {
+	if (mode === "single") {
 		await runEntry(entries[0]!, run);
 		signal?.throwIfAborted();
 		return;
 	}
-	if (workflow.mode === "parallel") {
+	if (mode === "parallel") {
 		await Promise.all(entries.map((entry) => runEntry(entry, run)));
 		signal?.throwIfAborted();
 		return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "22.0.1",
+  "version": "22.2.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent/SKILL.md

@@ -26,10 +26,10 @@ Use one compact `role`/`name`/`task` packet, `tasks` for independent packets, or
 
 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 and preserves declared order.
 
-Every changeset advances 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. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for input. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.
+Every changeset advances 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. 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. Inspect `subagent_status` and use `subagent_stage` with the exact `generation`, `taskId`, `attempt`, candidate `tip`, and `expectedTip` to select and merge candidates into the owned integration checkout in explicit order. Resolve conflicts there and verify with `resolve`; never edit Main to resolve them. For dependents, `subagent_integrate advance` runs ready tasks against the exact staged snapshot. When selected work is staged, use `subagent_integrate validate` on the exact `combinedTip` for full root checks and optional final judgment; `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.
+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` for full root checks and optional final judgment; `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.
 
-Use `subagent_status` to inspect 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. `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. 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; it may finish once all are released. 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.
+After a coordinator interruption in the canonical repository, ask the user to run `/subagent recover` once: it acquires the productive lease, classifies orphaned interruptions, 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. 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. `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. 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; it may finish once all are released. 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.

package/docs/delegation-routing.html

@@ -1,89 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Delegation routing and checked task lifecycle</title>
-<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap" rel="stylesheet">
-<style>
-  * { box-sizing: border-box; } body { margin: 0; padding: 32px; background: #f0eee9; color: #101828; font-family: 'Geist', sans-serif; }
-  main { max-width: 1280px; margin: auto; } h1 { font: 400 28px 'Instrument Serif', serif; margin: 0 0 16px; }
-  svg { display: block; width: 100%; height: auto; }
-</style>
-</head>
-<body><main><h1>Delegation routing and checked task lifecycle</h1>
-<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="delegation-routing-title delegation-routing-desc">
-<title id="delegation-routing-title">Delegation routing and checked task lifecycle</title>
-<desc id="delegation-routing-desc">A read-only Role runs direct in the current workspace; implementation uses an isolated checked graph. In that graph workers produce a checked candidate, Main stages and validates the combined tip, then explicitly promotes it. Interruptions retain work for recovery and revalidation.</desc>
-<defs>
-<marker id="routing-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-<marker id="routing-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
-<marker id="routing-arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-</defs>
-<rect width="1280" height="720" fill="#f0eee9"/>
-<text x="48" y="60" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1.5">PI SUBAGENT / ROUTING + LIFECYCLE</text>
-<text x="48" y="99" fill="#101828" font-family="'Instrument Serif',serif" font-size="28">One explicit mode; only checked work can be promoted</text>
-<text x="48" y="126" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Direct work returns an observed result. Isolated changesets yield a candidate that Main must validate and promote.</text>
-<!-- Routes and transitions are drawn before nodes. -->
-<line x1="224" y1="212" x2="248" y2="212" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M336 268 V296 Q336 304 328 304 H192 Q184 304 184 312 V352" fill="none" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M424 212 H488 Q496 212 496 220 V352" fill="none" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<line x1="560" y1="400" x2="624" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="784" y1="400" x2="848" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="1008" y1="400" x2="1072" y2="400" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<!-- Interruption / re-entry paths use separate attach points. -->
-<line x1="448" y1="448" x2="448" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="512" y1="512" x2="512" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="896" y1="448" x2="896" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="960" y1="512" x2="960" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<!-- Arrow labels have an 8px gap to their strokes. -->
-<g fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" text-anchor="middle">
-<rect x="256" y="284" width="48" height="12" rx="2" fill="#f0eee9"/><text x="280" y="293">YES</text>
-<rect x="432" y="192" width="72" height="12" rx="2" fill="#f0eee9"/><text x="468" y="201" fill="#1d4ed8">NO / GRAPH</text>
-<rect x="568" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="592" y="389">CHECK</text>
-<rect x="792" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="816" y="389">STAGE</text>
-<rect x="1016" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="1040" y="389" fill="#1d4ed8">VERIFY</text>
-<rect x="384" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="412" y="481">PAUSE</text>
-<rect x="520" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="548" y="481">RESUME</text>
-<rect x="816" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="852" y="481">MAIN DRIFT</text>
-<rect x="968" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="1004" y="481">RECHECK</text>
-</g>
-<!-- Mode selection. -->
-<rect x="80" y="180" width="144" height="64" rx="24" fill="#ffffff" stroke="#101828"/>
-<text x="152" y="217" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Delegate task</text>
-<polygon points="336,156 424,212 336,268 248,212" fill="#ffffff" stroke="#101828"/>
-<text x="336" y="208" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Direct</text>
-<text x="336" y="226" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">eligible?</text>
-<!-- Direct is intentionally a single terminal branch: no worktree or candidate. -->
-<text x="80" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">DIRECT</text>
-<rect x="80" y="352" width="208" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="184" y="384" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Herdr tabs</text>
-<text x="184" y="406" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Current workspace</text>
-<text x="184" y="428" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Observe result</text>
-<text x="80" y="477" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Single · parallel · chain</text>
-<!-- Isolated changeset rail. -->
-<text x="400" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">ISOLATED / CHECKED CHANGESET</text>
-<rect x="400" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="480" y="387" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Saved + working</text>
-<text x="480" y="411" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Durable ID</text>
-<text x="480" y="429" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Owned worktree</text>
-<rect x="624" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="704" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Ready candidate</text>
-<text x="704" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Clean commit + checks</text>
-<rect x="848" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="928" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Staged by Main</text>
-<text x="928" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Exact candidate tip</text>
-<rect x="1072" y="352" width="160" height="96" rx="8" fill="#1d4ed8" fill-opacity="0.08" stroke="#1d4ed8"/>
-<text x="1152" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Promoted by Main</text>
-<text x="1152" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">After combined checks</text>
-<!-- Recovery states do not erase or bypass exact checks. -->
-<text x="400" y="497" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">WAIT / RECOVERY</text>
-<rect x="400" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="480" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Needs attention</text>
-<text x="480" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Status / retry</text>
-<rect x="848" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="928" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Revalidate</text>
-<text x="928" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Restage if needed</text>
-<line x1="48" y1="648" x2="1232" y2="648" stroke="#101828" stroke-opacity="0.12"/>
-<text x="48" y="674" fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">GUARD</text>
-<text x="128" y="674" fill="#101828" font-family="'Geist',sans-serif" font-size="12">No fallback between modes. Failed validation retains evidence; abort requires no retained work.</text>
-</svg></main></body></html>

package/docs/delegation-routing.svg

@@ -1,78 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="delegation-routing-title delegation-routing-desc">
-<title id="delegation-routing-title">Delegation routing and checked task lifecycle</title>
-<desc id="delegation-routing-desc">A read-only Role runs direct in the current workspace; implementation uses an isolated checked graph. In that graph workers produce a checked candidate, Main stages and validates the combined tip, then explicitly promotes it. Interruptions retain work for recovery and revalidation.</desc>
-<defs>
-<style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap');</style>
-<marker id="routing-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-<marker id="routing-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
-<marker id="routing-arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
-</defs>
-<rect width="1280" height="720" fill="#f0eee9"/>
-<text x="48" y="60" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1.5">PI SUBAGENT / ROUTING + LIFECYCLE</text>
-<text x="48" y="99" fill="#101828" font-family="'Instrument Serif',serif" font-size="28">One explicit mode; only checked work can be promoted</text>
-<text x="48" y="126" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Direct work returns an observed result. Isolated changesets yield a candidate that Main must validate and promote.</text>
-<!-- Routes and transitions are drawn before nodes. -->
-<line x1="224" y1="212" x2="248" y2="212" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M336 268 V296 Q336 304 328 304 H192 Q184 304 184 312 V352" fill="none" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<path d="M424 212 H488 Q496 212 496 220 V352" fill="none" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<line x1="560" y1="400" x2="624" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="784" y1="400" x2="848" y2="400" stroke="#4c5665" marker-end="url(#routing-arrow)"/>
-<line x1="1008" y1="400" x2="1072" y2="400" stroke="#1d4ed8" stroke-width="1.4" marker-end="url(#routing-arrow-accent)"/>
-<!-- Interruption / re-entry paths use separate attach points. -->
-<line x1="448" y1="448" x2="448" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="512" y1="512" x2="512" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="896" y1="448" x2="896" y2="512" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<line x1="960" y1="512" x2="960" y2="448" stroke="#4c5665" stroke-dasharray="5,4" marker-end="url(#routing-arrow)"/>
-<!-- Arrow labels have an 8px gap to their strokes. -->
-<g fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" text-anchor="middle">
-<rect x="256" y="284" width="48" height="12" rx="2" fill="#f0eee9"/><text x="280" y="293">YES</text>
-<rect x="432" y="192" width="72" height="12" rx="2" fill="#f0eee9"/><text x="468" y="201" fill="#1d4ed8">NO / GRAPH</text>
-<rect x="568" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="592" y="389">CHECK</text>
-<rect x="792" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="816" y="389">STAGE</text>
-<rect x="1016" y="380" width="48" height="12" rx="2" fill="#f0eee9"/><text x="1040" y="389" fill="#1d4ed8">VERIFY</text>
-<rect x="384" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="412" y="481">PAUSE</text>
-<rect x="520" y="472" width="56" height="12" rx="2" fill="#f0eee9"/><text x="548" y="481">RESUME</text>
-<rect x="816" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="852" y="481">MAIN DRIFT</text>
-<rect x="968" y="472" width="72" height="12" rx="2" fill="#f0eee9"/><text x="1004" y="481">RECHECK</text>
-</g>
-<!-- Mode selection. -->
-<rect x="80" y="180" width="144" height="64" rx="24" fill="#ffffff" stroke="#101828"/>
-<text x="152" y="217" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Delegate task</text>
-<polygon points="336,156 424,212 336,268 248,212" fill="#ffffff" stroke="#101828"/>
-<text x="336" y="208" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Direct</text>
-<text x="336" y="226" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">eligible?</text>
-<!-- Direct is intentionally a single terminal branch: no worktree or candidate. -->
-<text x="80" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">DIRECT</text>
-<rect x="80" y="352" width="208" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="184" y="384" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Herdr tabs</text>
-<text x="184" y="406" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Current workspace</text>
-<text x="184" y="428" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Observe result</text>
-<text x="80" y="477" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Single · parallel · chain</text>
-<!-- Isolated changeset rail. -->
-<text x="400" y="336" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">ISOLATED / CHECKED CHANGESET</text>
-<rect x="400" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="480" y="387" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Saved + working</text>
-<text x="480" y="411" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Durable ID</text>
-<text x="480" y="429" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Owned worktree</text>
-<rect x="624" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="704" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Ready candidate</text>
-<text x="704" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Clean commit + checks</text>
-<rect x="848" y="352" width="160" height="96" rx="8" fill="#ffffff" stroke="#101828"/>
-<text x="928" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Staged by Main</text>
-<text x="928" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Exact candidate tip</text>
-<rect x="1072" y="352" width="160" height="96" rx="8" fill="#1d4ed8" fill-opacity="0.08" stroke="#1d4ed8"/>
-<text x="1152" y="390" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Promoted by Main</text>
-<text x="1152" y="416" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">After combined checks</text>
-<!-- Recovery states do not erase or bypass exact checks. -->
-<text x="400" y="497" fill="#6a7282" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">WAIT / RECOVERY</text>
-<rect x="400" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="480" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Needs attention</text>
-<text x="480" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Status / retry</text>
-<rect x="848" y="512" width="160" height="72" rx="8" fill="#e6e4de" stroke="#4c5665" stroke-dasharray="5,4"/>
-<text x="928" y="541" text-anchor="middle" fill="#101828" font-family="'Geist',sans-serif" font-size="12" font-weight="600">Revalidate</text>
-<text x="928" y="562" text-anchor="middle" fill="#4c5665" font-family="'Geist',sans-serif" font-size="12">Restage if needed</text>
-<line x1="48" y1="648" x2="1232" y2="648" stroke="#101828" stroke-opacity="0.12"/>
-<text x="48" y="674" fill="#4c5665" font-family="'Geist Mono',monospace" font-size="8" letter-spacing="1">GUARD</text>
-<text x="128" y="674" fill="#101828" font-family="'Geist',sans-serif" font-size="12">No fallback between modes. Failed validation retains evidence; abort requires no retained work.</text>
-</svg>

package/extensions/task-name.ts

@@ -1,28 +0,0 @@
-import { DISPLAY_TEXT_CONTRACT } from "@henryqw/pi-subagent";
-import { Type, type Static } from "typebox";
-
-const TASK_NAME_MAX_LENGTH = 29 as const;
-const TASK_NAME_LIMIT_WORDING = `about five words and fewer than ${TASK_NAME_MAX_LENGTH + 1} characters`;
-
-export const TASK_NAME_CONTRACT = {
-	minLength: 1,
-	maxLength: TASK_NAME_MAX_LENGTH,
-	description: `Short descriptive task name, ${TASK_NAME_LIMIT_WORDING}; C0/C1 control characters are rejected.`,
-	controlRanges: DISPLAY_TEXT_CONTRACT.controlRanges,
-	pattern: DISPLAY_TEXT_CONTRACT.pattern,
-} as const;
-
-export const TaskNameSchema = Type.String({
-	minLength: TASK_NAME_CONTRACT.minLength,
-	maxLength: TASK_NAME_CONTRACT.maxLength,
-	description: TASK_NAME_CONTRACT.description,
-	pattern: TASK_NAME_CONTRACT.pattern,
-});
-
-export type TaskName = Static<typeof TaskNameSchema>;
-
-export function normalizeTaskName(value: TaskName, path: string): TaskName {
-	const normalized = value.trim();
-	if (!normalized) throw new Error(`${path} must be non-empty text.`);
-	return normalized;
-}