@narumitw/pi-subagents 2.0.6 → 2.1.0

package/src/completion-render.ts

@@ -139,6 +139,7 @@ function renderStatus(state: string): RenderStatus {
 			return "interrupted";
 		case "closed":
 			return "closed";
+		case "partial":
 		case "blocked":
 		case "needs-input":
 		case "abstained":

package/src/completion-requirement.ts

@@ -0,0 +1,308 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
+import type { AgentLifecycleState, ManagedAgent } from "./registry-types.js";
+
+export const COMPLETION_REQUIREMENT_MODES = ["background", "required"] as const;
+export type CompletionRequirementMode = (typeof COMPLETION_REQUIREMENT_MODES)[number];
+
+export const CompletionRequirementModeSchema = StringEnum(COMPLETION_REQUIREMENT_MODES, {
+	description:
+		"Mark this exact turn as background (default) or required for the parent final answer. Required results are tracked until their exact completion becomes visible, but current Pi versions do not provide a hard pre-display final-answer barrier.",
+	default: "background",
+});
+
+export const COMPLETION_REQUIREMENT_VERSION = "pi-subagents:completion-requirement:v1" as const;
+export const COMPLETION_REQUIREMENT_CONTEXT_TYPE = "pi-subagent-required-completions";
+const MAX_REQUIREMENTS_PER_AGENT = 20;
+export const MAX_UNRESOLVED_REQUIRED_COMPLETIONS = 64;
+
+export type CompletionRequirementState = "pending" | "available" | "visible" | "cancelled";
+
+export interface CompletionRequirementRecord {
+	version: typeof COMPLETION_REQUIREMENT_VERSION;
+	runId: string;
+	generation: number;
+	state: CompletionRequirementState;
+	createdAt: number;
+	updatedAt: number;
+	completionId?: string;
+	terminalState?: AgentLifecycleState;
+}
+
+export function beginCompletionRequirement(
+	records: readonly CompletionRequirementRecord[] | undefined,
+	input: { runId: string; generation: number; createdAt: number },
+): CompletionRequirementRecord[] {
+	const retained = (records ?? []).filter(
+		(record) => record.runId !== input.runId || record.generation !== input.generation,
+	);
+	retained.push({
+		version: COMPLETION_REQUIREMENT_VERSION,
+		runId: input.runId,
+		generation: input.generation,
+		state: "pending",
+		createdAt: input.createdAt,
+		updatedAt: input.createdAt,
+	});
+	return retained.slice(-MAX_REQUIREMENTS_PER_AGENT);
+}
+
+export function makeCompletionAvailable(
+	records: readonly CompletionRequirementRecord[] | undefined,
+	input: {
+		runId: string;
+		generation: number;
+		completionId: string;
+		terminalState: AgentLifecycleState;
+		updatedAt: number;
+	},
+): CompletionRequirementRecord[] | undefined {
+	return updateExact(records, input.runId, input.generation, (record) => ({
+		...record,
+		state: "available",
+		completionId: input.completionId,
+		terminalState: input.terminalState,
+		updatedAt: input.updatedAt,
+	}));
+}
+
+export function makeCompletionVisible(
+	records: readonly CompletionRequirementRecord[] | undefined,
+	completionId: string,
+	updatedAt: number,
+): CompletionRequirementRecord[] | undefined {
+	if (!records?.some((record) => record.completionId === completionId)) {
+		return records?.map((record) => ({ ...record }));
+	}
+	return records.map((record) =>
+		record.completionId === completionId
+			? { ...record, state: "visible" as const, updatedAt }
+			: { ...record },
+	);
+}
+
+export function cancelPendingCompletionRequirements(
+	records: readonly CompletionRequirementRecord[] | undefined,
+	terminalState: AgentLifecycleState,
+	updatedAt: number,
+): CompletionRequirementRecord[] | undefined {
+	if (!records?.some((record) => record.state === "pending")) {
+		return records?.map((record) => ({ ...record }));
+	}
+	return records.map((record) =>
+		record.state === "pending"
+			? {
+					...record,
+					state: "cancelled" as const,
+					terminalState,
+					updatedAt,
+				}
+			: { ...record },
+	);
+}
+
+export function requirementForCompletion(
+	agent: Pick<ManagedAgent, "completionRequirements">,
+	completionId: string,
+): CompletionRequirementRecord | undefined {
+	return agent.completionRequirements?.find((record) => record.completionId === completionId);
+}
+
+export interface BranchCompletionRequirementState {
+	observedState: boolean;
+	records: Map<string, CompletionRequirementRecord>;
+	keys: Set<string>;
+}
+
+export function completionRequirementKey(
+	record: Pick<CompletionRequirementRecord, "runId" | "generation">,
+): string {
+	return `${record.runId}\u0000${record.generation}`;
+}
+
+export function completionRequirementsFromBranch(
+	entries: readonly unknown[],
+): BranchCompletionRequirementState {
+	const records = new Map<string, CompletionRequirementRecord>();
+	let observedState = false;
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const candidate = entry as Record<string, unknown>;
+		const message =
+			candidate.type === "message" && candidate.message && typeof candidate.message === "object"
+				? (candidate.message as Record<string, unknown>)
+				: candidate;
+		if (
+			message.role === "toolResult" &&
+			["subagent_spawn", "subagent_send", "subagent_await", "subagent_manage"].includes(
+				String(message.toolName),
+			)
+		) {
+			observedState = true;
+			const details = message.details;
+			if (!details || typeof details !== "object" || Array.isArray(details)) continue;
+			const detailsRecord = details as Record<string, unknown>;
+			const agents = [
+				detailsRecord.agent,
+				...(Array.isArray(detailsRecord.agents) ? detailsRecord.agents : []),
+			];
+			for (const agent of agents) {
+				if (!agent || typeof agent !== "object" || Array.isArray(agent)) continue;
+				const requirements = (agent as Record<string, unknown>).completionRequirements;
+				if (!Array.isArray(requirements)) continue;
+				for (const requirement of requirements) {
+					if (isCompletionRequirementRecord(requirement)) {
+						records.set(completionRequirementKey(requirement), { ...requirement });
+					}
+				}
+			}
+			continue;
+		}
+		if (message.role !== "custom" || message.customType !== "pi-subagent-completion") continue;
+		const details = message.details;
+		if (!details || typeof details !== "object" || Array.isArray(details)) continue;
+		const detailRecord = details as Record<string, unknown>;
+		const completionRecords = Array.isArray(detailRecord.completions)
+			? detailRecord.completions
+			: [detailRecord];
+		for (const completion of completionRecords) {
+			if (!completion || typeof completion !== "object" || Array.isArray(completion)) continue;
+			const requirement = (completion as Record<string, unknown>).completionRequirement;
+			if (!isCompletionRequirementRecord(requirement)) continue;
+			records.set(completionRequirementKey(requirement), {
+				...requirement,
+				state: "visible",
+			});
+		}
+	}
+	return { observedState, records, keys: new Set(records.keys()) };
+}
+
+export function pendingRequiredCompletionCount(
+	agent: Pick<ManagedAgent, "completionRequirements">,
+): number {
+	return (agent.completionRequirements ?? []).filter(
+		(record) => record.state === "pending" || record.state === "available",
+	).length;
+}
+
+export function reconcileRequiredCompletionContext(
+	messages: ContextEvent["messages"],
+	agents: readonly ManagedAgent[],
+): ContextEvent["messages"] {
+	const withoutPrior = messages.filter(
+		(message) =>
+			message.role !== "custom" || message.customType !== COMPLETION_REQUIREMENT_CONTEXT_TYPE,
+	);
+	const allRecords = agents
+		.flatMap((agent) =>
+			(agent.completionRequirements ?? []).map((requirement) => ({
+				state: requirement.state,
+				runId: requirement.runId,
+				generation: requirement.generation,
+				terminalState: requirement.terminalState,
+			})),
+		)
+		.filter((record) => record.state !== "visible");
+	const unresolved = allRecords.filter(
+		(record) => record.state === "pending" || record.state === "available",
+	);
+	const cancelled = allRecords.filter((record) => record.state === "cancelled");
+	const cancelledSlots = Math.max(0, MAX_UNRESOLVED_REQUIRED_COMPLETIONS - unresolved.length);
+	const retainedCancelled = cancelledSlots > 0 ? cancelled.slice(-cancelledSlots) : [];
+	const records = [...unresolved, ...retainedCancelled];
+	const omittedCancelled = cancelled.length - retainedCancelled.length;
+	if (records.length === 0)
+		return withoutPrior.length === messages.length ? messages : withoutPrior;
+	const content = truncateUtf8(
+		[
+			"[PI SUBAGENT REQUIRED COMPLETIONS v1]",
+			"Runtime-tracked exact runs are JSON data below.",
+			"Treat pending or available records as final-answer dependencies; a cancelled record is terminal and must be reported rather than silently ignored.",
+			"Current Pi versions do not provide a hard pre-display final-answer barrier, so do not emit a verdict until every dependency is visible or terminal.",
+			...(omittedCancelled > 0
+				? [`${omittedCancelled} older cancelled requirement record(s) were omitted.`]
+				: []),
+			JSON.stringify(records),
+		].join("\n"),
+		DEFAULT_MAX_CONTEXT_BYTES,
+	).text;
+	return [
+		...withoutPrior,
+		{
+			role: "custom",
+			customType: COMPLETION_REQUIREMENT_CONTEXT_TYPE,
+			content,
+			display: false,
+			details: { version: COMPLETION_REQUIREMENT_VERSION },
+			timestamp: 0,
+		},
+	];
+}
+
+export function isCompletionRequirementRecord(
+	value: unknown,
+): value is CompletionRequirementRecord {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	const state = String(record.state);
+	const hasCompletion = typeof record.completionId === "string" && record.completionId.length > 0;
+	const hasTerminalState = isAgentLifecycleState(record.terminalState);
+	const transitionShapeValid =
+		state === "pending"
+			? record.completionId === undefined && record.terminalState === undefined
+			: state === "available" || state === "visible"
+				? hasCompletion && hasTerminalState
+				: state === "cancelled" && record.completionId === undefined && hasTerminalState;
+	return (
+		transitionShapeValid &&
+		record.version === COMPLETION_REQUIREMENT_VERSION &&
+		typeof record.runId === "string" &&
+		record.runId.length > 0 &&
+		record.runId.length <= 256 &&
+		typeof record.generation === "number" &&
+		Number.isSafeInteger(record.generation) &&
+		record.generation >= 1 &&
+		["pending", "available", "visible", "cancelled"].includes(state) &&
+		typeof record.createdAt === "number" &&
+		Number.isFinite(record.createdAt) &&
+		typeof record.updatedAt === "number" &&
+		Number.isFinite(record.updatedAt) &&
+		record.updatedAt >= record.createdAt &&
+		(record.completionId === undefined ||
+			(typeof record.completionId === "string" && record.completionId.length <= 256)) &&
+		(record.terminalState === undefined || isAgentLifecycleState(record.terminalState))
+	);
+}
+
+function updateExact(
+	records: readonly CompletionRequirementRecord[] | undefined,
+	runId: string,
+	generation: number,
+	update: (record: CompletionRequirementRecord) => CompletionRequirementRecord,
+): CompletionRequirementRecord[] | undefined {
+	if (!records?.some((record) => record.runId === runId && record.generation === generation)) {
+		return records?.map((record) => ({ ...record }));
+	}
+	return records.map((record) =>
+		record.runId === runId && record.generation === generation ? update(record) : { ...record },
+	);
+}
+
+function isAgentLifecycleState(value: unknown): value is AgentLifecycleState {
+	return [
+		"starting",
+		"running",
+		"idle",
+		"completed",
+		"partial",
+		"blocked",
+		"needs-input",
+		"abstained",
+		"stale",
+		"interrupted",
+		"failed",
+		"closed",
+	].includes(String(value));
+}

package/src/config-registration.ts

@@ -3,9 +3,9 @@ import { cachedModuleLoader } from "./cached-module-loader.js";
 import type { SubagentMenuOwner, SubagentSettingsRuntime } from "./config-ui.js";
 
 const SUBCOMMANDS = [
-	{ value: "settings", label: "settings", description: "Configure subagent user settings" },
-	{ value: "status", label: "status", description: "Show effective subagent settings" },
-	{ value: "help", label: "help", description: "Show subagent settings help" },
+	{ value: "settings", label: "settings", description: "Open grouped subagent settings" },
+	{ value: "status", label: "status", description: "Show detailed subagent diagnostics" },
+	{ value: "help", label: "help", description: "Show subagent first steps and safety help" },
 ];
 
 type ConfigUiModule = Pick<
@@ -50,7 +50,7 @@ export function registerSubagentConfigCommand(
 		dependencies.loadConfigStatus ?? (() => import("./config-status.js")),
 	);
 	pi.registerCommand("subagents", {
-		description: "Manage current-session subagents and user settings",
+		description: "Manage subagents, settings, diagnostics, and help",
 		getArgumentCompletions(prefix: string) {
 			const normalized = prefix.trim().toLowerCase();
 			const matches = SUBCOMMANDS.filter((item) => item.value.startsWith(normalized));
@@ -103,7 +103,7 @@ export function registerSubagentConfigCommand(
 				}
 				if (!isCurrent()) return;
 				if (!subcommand) await configUi.showSubagentManager(pi, ctx, runtime, owner);
-				else await configUi.showSubagentSettings(ctx, runtime, owner);
+				else await configUi.showSubagentSettings(pi, ctx, runtime, owner);
 				return;
 			}
 			if (ctx.mode === "tui" || ctx.hasUI) {

package/src/config-status.ts

@@ -16,14 +16,15 @@ import {
 	inspectDelegationWorkflowSettings,
 	inspectStatefulLimitSettings,
 	inspectStatefulTransportSettings,
+	inspectUsageRecordingSettings,
 } from "./settings.js";
 import type { StatefulSubagentRuntimeStatus } from "./stateful.js";
 import {
 	formatConfiguredDetachedLimitDivergence,
-	formatConfiguredDetachedLimits,
 	formatDetachedLimitSummary,
 } from "./stateful-limit-ui.js";
 import { STATEFUL_LIMIT_DEFINITIONS } from "./stateful-limits.js";
+import { USAGE_RECORDING_RETENTION_DAYS } from "./usage-recording-config.js";
 import { workflowLabel } from "./workflow-ui.js";
 
 export function showSubagentStatus(
@@ -51,32 +52,30 @@ export function statusLines(runtime: SubagentSettingsRuntime): string[] {
 	return formatStatus(runtime.getRuntimeStatus(), snapshot, runtime).split("\n");
 }
 
-export function helpLines(runtime: SubagentSettingsRuntime): string[] {
-	const snapshot = inspectCompletionDeliverySettings();
-	const cwdPolicy = inspectCwdPolicySettings();
-	const parallelLimit = inspectBlockingParallelLimitSettings();
-	const detachedLimits = inspectStatefulLimitSettings();
-	const transport = inspectStatefulTransportSettings();
+export function helpLines(_runtime: SubagentSettingsRuntime): string[] {
 	return [
-		"/subagents — choose delegation workflow, manage current agents, and configure agent tools",
-		"/subagents settings — configure target locations, trusted resources, and async completion",
-		"/subagents status — show current-session and user-setting values",
-		"/subagents help — show this help",
-		"Target policies control startup directories and resources, not filesystem access or sandboxing.",
-		"Manage saved folder trust with Pi /trust and restart Pi after changing it.",
-		`Runtime consultation target: ${consultationCwdLabel(runtime.getConsultationCwdPolicy())}`,
-		`Configured consultation target: ${consultationCwdLabel(cwdPolicy.consultation.value)} (${cwdPolicy.consultation.source})`,
-		`Runtime delegation target: ${delegationCwdLabel(runtime.getDelegationCwdPolicy())}`,
-		`Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)} (${cwdPolicy.delegation.source})`,
-		`Maximum parallel workers: ${runtime.getMaxParallelTasks()} per blocking call`,
-		`Configured parallel limit: ${parallelLimit.value} (${parallelLimit.source})`,
-		`Detached limits: ${formatDetachedLimitSummary(runtime.getRuntimeStatus())}`,
-		`Configured transport: ${transport.value} (${transport.source})`,
-		...(detachedLimits.values
-			? [`Configured detached limits: ${formatConfiguredDetachedLimits(detachedLimits.values)}`]
-			: ["Configured detached limits: unavailable; repair user settings"]),
-		"Detached limits and transport apply after /reload; clear retained agents first if their work must not be interrupted.",
-		`User settings: ${safeTerminalText(snapshot.path)}`,
+		"Start here",
+		"  1. Open How subagents run.",
+		"  2. Choose the workflow that matches the tools and blocking behavior you need.",
+		"  3. Open Completion and privacy if Pi must use background results in the current answer.",
+		"The blocking subagent tool is deprecated and remains available only in compatibility workflows.",
+		"subagent_consult and subagent_await remain supported.",
+		"Current subagents shows work in progress and subagents saved for follow-up.",
+		"Settings",
+		"  Folders and trusted resources — choose where subagents start and what consultations load.",
+		"  Completion and privacy — choose what Pi does when work finishes and whether usage is recorded.",
+		"  Agent defaults — choose tools, model, thinking effort, and time limit for each subagent.",
+		"  Advanced runtime settings — optional transport and capacity controls.",
+		"Changes are saved immediately.",
+		"Transport and background-agent limits apply after /reload.",
+		"Commands",
+		"  /subagents — open the manager",
+		"  /subagents settings — open Settings",
+		"  /subagents status — show detailed diagnostics",
+		"  /subagents help — show this help",
+		"Safety",
+		"Folder choices control starting locations and loaded resources; they do not sandbox files, commands, or network access.",
+		"Manage saved folder trust with Pi /trust, then restart Pi.",
 	];
 }
 
@@ -86,34 +85,20 @@ export function formatManagerSummary(
 	configured: ReturnType<typeof inspectDelegationWorkflowSettings>,
 ): string {
 	const current = currentWorkflow(runtime, status);
-	const cwdPolicy = inspectCwdPolicySettings();
-	const consult = inspectConsultResourceSettings();
 	const detachedLimits = inspectStatefulLimitSettings();
-	const transport = inspectStatefulTransportSettings();
 	const detachedDivergence = detachedLimits.values
 		? formatConfiguredDetachedLimitDivergence(status, detachedLimits.values)
 		: undefined;
 	return [
-		`Delegation: ${workflowLabel(current)}`,
-		`Completion: ${completionLabel(status.completionDelivery)}`,
-		`Consult target: ${consultationCwdLabel(runtime.getConsultationCwdPolicy())}`,
-		`Delegation target: ${delegationCwdLabel(runtime.getDelegationCwdPolicy())}`,
-		`Consult resources: ${consultResourceLabel(runtime.getConsultResourcePolicy())}`,
-		`Parallel workers: max ${runtime.getMaxParallelTasks()} per blocking call`,
-		`Detached limits: ${formatDetachedLimitSummary(status)}`,
-		`Transport: ${status.transport}`,
-		`Configured transport: ${transport.value} · ${transport.source}`,
-		`Configured consult target: ${consultationCwdLabel(cwdPolicy.consultation.value)} · ${cwdPolicy.consultation.source}`,
-		`Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)} · ${cwdPolicy.delegation.source}`,
-		`Configured consult resources: ${consultResourceLabel(consult.value)} · ${consult.source}`,
-		`Settings: ${safeTerminalText(cwdPolicy.path)}`,
-		`Agents: ${status.activeAgents} active · ${status.retainedAgents} retained`,
-		...(detachedDivergence ? [detachedDivergence] : []),
+		`How subagents run: ${workflowLabel(current)}`,
+		`Subagents: ${status.activeAgents} working · ${status.retainedAgents} saved for follow-up`,
+		`When work finishes: ${completionLabel(status.completionDelivery)}`,
 		...(configured.value !== current
 			? [`Configured after reload: ${workflowLabel(configured.value)}`]
 			: []),
+		...(detachedDivergence ? [detachedDivergence] : []),
 		...(configured.error || detachedLimits.error
-			? ["Settings need repair; open Advanced settings for details."]
+			? ["Action needed: Repair user settings. Open Diagnostics for details."]
 			: []),
 	].join("\n");
 }
@@ -129,27 +114,33 @@ function formatStatus(
 	const parallelLimit = inspectBlockingParallelLimitSettings();
 	const detachedLimits = inspectStatefulLimitSettings();
 	const transport = inspectStatefulTransportSettings();
+	const usageRecording = inspectUsageRecordingSettings();
 	const current = runtime ? currentWorkflow(runtime, status) : configuredWorkflow.value;
+	const usageStatus = runtime?.getUsageRecordingStatus?.();
 	return [
-		"Current session",
-		`  Delegation: ${workflowLabel(current)}`,
-		`  Async runtime: ${status.initialized ? "initialized" : status.enabled ? "not initialized" : "disabled"}`,
+		"Current Session",
+		`  How subagents run: ${workflowLabel(current)}`,
+		`  Background runtime: ${status.initialized ? "initialized" : status.enabled ? "not initialized" : "disabled"}`,
 		`  Transport: ${status.transport}`,
 		`  Configured transport: ${transport.value} (${transport.source})`,
-		`  Completion: ${completionLabel(status.completionDelivery)}`,
-		`  Consultation target: ${consultationCwdLabel(runtime?.getConsultationCwdPolicy() ?? cwdPolicy.consultation.value)}`,
-		`  Delegation target: ${delegationCwdLabel(runtime?.getDelegationCwdPolicy() ?? cwdPolicy.delegation.value)}`,
-		`  Consultation resources: ${consultResourceLabel(runtime?.getConsultResourcePolicy() ?? consult.value)}`,
-		`  Maximum parallel workers: ${runtime?.getMaxParallelTasks() ?? parallelLimit.value} per blocking call`,
-		`  Detached limits: ${formatDetachedLimitSummary(status)}`,
-		`  Agents: ${status.activeAgents} active, ${status.retainedAgents} retained`,
-		"User settings",
-		`  Delegation source: ${configuredWorkflow.source}`,
-		`  Configured delegation: ${workflowLabel(configuredWorkflow.value)}`,
+		`  When work finishes: ${completionLabel(status.completionDelivery)}`,
+		`  Read-only consultation folders: ${consultationCwdLabel(runtime?.getConsultationCwdPolicy() ?? cwdPolicy.consultation.value)}`,
+		`  Subagent folders: ${delegationCwdLabel(runtime?.getDelegationCwdPolicy() ?? cwdPolicy.delegation.value)}`,
+		`  Read-only consultation resources: ${consultResourceLabel(runtime?.getConsultResourcePolicy() ?? consult.value)}`,
+		`  Blocking worker limit: ${runtime?.getMaxParallelTasks() ?? parallelLimit.value} per request`,
+		`  Background-agent limits: ${formatDetachedLimitSummary(status)}`,
+		`  Subagents: ${status.activeAgents} working, ${status.retainedAgents} saved for follow-up`,
+		`  Local usage recording: ${usageStatus?.enabled ? "enabled" : "disabled"}`,
+		`  Recorded events this session: ${usageStatus?.recordedEvents ?? 0}`,
+		`  Usage retention: ${usageStatus?.retentionDays ?? USAGE_RECORDING_RETENTION_DAYS} days`,
+		`  Usage path: ${safeTerminalText(usageStatus?.path ?? "unavailable")}`,
+		"User Settings",
+		`  Workflow source: ${configuredWorkflow.source}`,
+		`  Configured workflow: ${workflowLabel(configuredWorkflow.value)}`,
 		`  Completion source: ${snapshot.source}`,
 		`  Configured completion: ${completionLabel(snapshot.value)}`,
-		`  Configured parallel limit: ${parallelLimit.value}`,
-		`  Parallel limit source: ${parallelLimit.source}`,
+		`  Configured blocking worker limit: ${parallelLimit.value}`,
+		`  Blocking worker limit source: ${parallelLimit.source}`,
 		...(detachedLimits.values
 			? STATEFUL_LIMIT_DEFINITIONS.map((definition) => {
 					const configured = detachedLimits.values?.[definition.field];
@@ -162,17 +153,20 @@ function formatStatus(
 		`  Delegation target source: ${cwdPolicy.delegation.source}`,
 		`  Configured consultation resources: ${consultResourceLabel(consult.value)}`,
 		`  Consultation resource source: ${consult.source}`,
+		`  Configured usage recording: ${usageRecording.enabled ? "enabled" : "disabled"}`,
+		`  Usage recording source: ${usageRecording.source}`,
 		`  Path: ${safeTerminalText(snapshot.path)}`,
 		configuredWorkflow.error ||
 		snapshot.error ||
 		cwdPolicy.error ||
 		parallelLimit.error ||
 		detachedLimits.error ||
-		transport.error
-			? `  Warning: ${safeTerminalText(configuredWorkflow.error ?? snapshot.error ?? cwdPolicy.error ?? parallelLimit.error ?? detachedLimits.error ?? transport.error ?? "invalid settings")}`
+		transport.error ||
+		usageRecording.error
+			? `  Warning: ${safeTerminalText(configuredWorkflow.error ?? snapshot.error ?? cwdPolicy.error ?? parallelLimit.error ?? detachedLimits.error ?? transport.error ?? usageRecording.error ?? "invalid settings")}`
 			: "  Warning: none",
 		configuredWorkflow.value !== current
-			? "Configured delegation differs from this session. Run /reload to apply it."
+			? "The configured workflow differs from this session. Run /reload to apply it."
 			: "Manual file changes require /reload.",
 	].join("\n");
 }
@@ -189,23 +183,25 @@ export function currentWorkflow(
 }
 
 export function completionLabel(value: CompletionDelivery): string {
-	return value === "auto-resume" ? "Resume automatically when finished" : "Wait until my next turn";
+	return value === "auto-resume"
+		? "Continue automatically when work finishes"
+		: "Wait for my next message";
 }
 
 export function consultationCwdLabel(value: ConsultationCwdPolicy): string {
 	return value === "current-workspace"
-		? "Current workspace only"
-		: "Anywhere · untrusted targets inherit nothing";
+		? "This workspace only"
+		: "Any folder · no project resources when untrusted";
 }
 
 export function delegationCwdLabel(value: DelegationCwdPolicy): string {
 	switch (value) {
 		case "trusted-targets":
-			return "Current or saved-trusted folders";
+			return "This workspace or saved-trusted folders";
 		case "current-workspace":
-			return "Current workspace only";
+			return "This workspace only";
 		case "anywhere":
-			return "Anywhere · normal Pi permissions";
+			return "Any folder Pi can access";
 	}
 }
 
@@ -214,7 +210,7 @@ export function consultResourceLabel(value: ConsultResourcePolicy): string {
 		case "project-context":
 			return "Project context only";
 		case "none":
-			return "No inherited resources";
+			return "No project resources";
 		case "all":
 			return "All trusted resources";
 	}