@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/params.ts

@@ -1,26 +1,124 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { type Static, Type } from "typebox";
 import { THINKING_LEVELS } from "./agents.js";
-import { MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
+import { DelegationContractSchema } from "./delegation-contract.js";
+import { MAX_CONFIGURABLE_PARALLEL_TASKS, MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
+import { PANEL_PRESETS } from "./panel-planning.js";
+import { SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
+import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 
 const TimeoutMs = Type.Number({
 	description:
-		"Hard timeout in milliseconds for each subagent subprocess. Defaults to PI_SUBAGENT_TIMEOUT_MS or 600000.",
+		"Work deadline in milliseconds selected for the task difficulty. On expiry, Pi aborts the work and makes one separately bounded summary attempt. Defaults to PI_SUBAGENT_TIMEOUT_MS or 600000.",
 	minimum: 1,
 	maximum: MAX_SUBAGENT_TIMEOUT_MS,
 });
 
+const TurnLimitFields = {
+	idleTimeoutMs: Type.Optional(
+		Type.Integer({
+			description:
+				"Maximum milliseconds without a completed assistant turn or tool result before Pi aborts work and preserves a checkpoint.",
+			minimum: 1,
+			maximum: MAX_SUBAGENT_TIMEOUT_MS,
+		}),
+	),
+	maxTurns: Type.Optional(
+		Type.Integer({
+			description: "Maximum assistant turns before unfinished work is stopped and checkpointed.",
+			minimum: 1,
+			maximum: MAX_SUBAGENT_TURNS,
+		}),
+	),
+	maxToolCalls: Type.Optional(
+		Type.Integer({
+			description: "Maximum tool calls before additional tool work is stopped and checkpointed.",
+			minimum: 1,
+			maximum: MAX_SUBAGENT_TOOL_CALLS,
+		}),
+	),
+};
+
 const ThinkingLevelSchema = StringEnum(THINKING_LEVELS, {
 	description:
 		"Pi thinking level for the subagent process: off, minimal, low, medium, high, xhigh, or max.",
 });
 
+const ResultFormatSchema = StringEnum(SUBAGENT_RESULT_FORMATS, {
+	description:
+		"Optional completion contract. Text preserves ordinary output; structured-v1 and structured-v2 request versioned JSON with bounded text fallback.",
+});
+
+const ContractFields = {
+	contract: Type.Optional(DelegationContractSchema),
+	resultFormat: Type.Optional(ResultFormatSchema),
+	retryPolicy: Type.Optional(
+		Type.Object(
+			{
+				maxAttempts: Type.Integer({ minimum: 1, maximum: 3 }),
+				backoffMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 30_000 })),
+			},
+			{ additionalProperties: false },
+		),
+	),
+	hedgeAfterMs: Type.Optional(Type.Integer({ minimum: 1, maximum: 30_000 })),
+};
+
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate to the agent" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	timeoutMs: Type.Optional(TimeoutMs),
+	...TurnLimitFields,
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	...ContractFields,
+});
+
+const WorkflowTaskItem = Type.Object({
+	id: Type.String({ minLength: 1, maxLength: 256 }),
+	agent: Type.Optional(
+		Type.String({ description: "Optional explicit agent; omit to route by capability manifest" }),
+	),
+	requiredCapabilities: Type.Optional(
+		Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 50 }),
+	),
+	requiredTools: Type.Optional(
+		Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 50 }),
+	),
+	requiredVerificationRole: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+	preferredCostHint: Type.Optional(StringEnum(["low", "medium", "high"] as const)),
+	preferredLatencyHint: Type.Optional(StringEnum(["low", "medium", "high"] as const)),
+	task: Type.String({ description: "Task to delegate to the agent" }),
+	dependsOn: Type.Optional(
+		Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 64 }),
+	),
+	inputArtifacts: Type.Optional(
+		Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 50 }),
+	),
+	inputArtifactVersions: Type.Optional(
+		Type.Record(
+			Type.String({ minLength: 1, maxLength: 256 }),
+			Type.String({ minLength: 1, maxLength: 256 }),
+		),
+	),
+	readPaths: Type.Optional(Type.Array(Type.String({ maxLength: 4096 }), { maxItems: 50 })),
+	writePaths: Type.Optional(Type.Array(Type.String({ maxLength: 4096 }), { maxItems: 50 })),
+	ownershipKeys: Type.Optional(Type.Array(Type.String({ maxLength: 256 }), { maxItems: 50 })),
+	acceptanceCriteria: Type.Optional(Type.Array(Type.String({ maxLength: 4096 }), { maxItems: 50 })),
+	integrationOwner: Type.Optional(Type.Boolean()),
+	verifierFor: Type.Optional(
+		Type.String({
+			minLength: 1,
+			maxLength: 256,
+			description:
+				"Target task ID for one distinct direct-dependent structured-v2 verifier. The executor gates target acceptance on a current exact-tree receipt.",
+		}),
+	),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	timeoutMs: Type.Optional(TimeoutMs),
+	...TurnLimitFields,
 	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	...ContractFields,
 });
 
 const ChainItem = Type.Object({
@@ -28,7 +126,9 @@ const ChainItem = Type.Object({
 	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	timeoutMs: Type.Optional(TimeoutMs),
+	...TurnLimitFields,
 	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	...ContractFields,
 });
 
 const AggregatorItem = Type.Object(
@@ -43,7 +143,9 @@ const AggregatorItem = Type.Object(
 			Type.String({ description: "Working directory for the aggregator process" }),
 		),
 		timeoutMs: Type.Optional(TimeoutMs),
+		...TurnLimitFields,
 		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+		...ContractFields,
 	},
 	{
 		description:
@@ -51,6 +153,48 @@ const AggregatorItem = Type.Object(
 	},
 );
 
+const PanelReviewerItem = Type.Object(
+	{
+		id: Type.String({ minLength: 1, maxLength: 256 }),
+		agent: Type.String({ minLength: 1 }),
+		focus: Type.Optional(Type.String({ maxLength: 8 * 1024 })),
+		timeoutMs: Type.Optional(TimeoutMs),
+		...TurnLimitFields,
+		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	},
+	{ additionalProperties: false },
+);
+
+const PanelSynthesizerItem = Type.Object(
+	{
+		agent: Type.String({ minLength: 1 }),
+		timeoutMs: Type.Optional(TimeoutMs),
+		...TurnLimitFields,
+		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	},
+	{ additionalProperties: false },
+);
+
+const PanelItem = Type.Object(
+	{
+		id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+		preset: Type.Optional(StringEnum(PANEL_PRESETS, { default: "custom" })),
+		task: Type.String({ minLength: 1, maxLength: 50 * 1024 }),
+		context: Type.Optional(Type.String({ maxLength: 50 * 1024 })),
+		reviewers: Type.Array(PanelReviewerItem, {
+			minItems: 2,
+			maxItems: MAX_CONFIGURABLE_PARALLEL_TASKS,
+		}),
+		synthesizer: PanelSynthesizerItem,
+		minValidReviews: Type.Optional(Type.Integer({ minimum: 2 })),
+	},
+	{
+		additionalProperties: false,
+		description:
+			"One bounded independent review round followed by one evidence-preserving synthesis when enough valid reviews remain.",
+	},
+);
+
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
 	description:
 		'Per-invocation custom agent scope. Default: "user". Use "project" for project-local agents or "both" for user and project agents; this is a tool argument, not a pi-subagents.json setting.',
@@ -63,12 +207,34 @@ export const SubagentParams = Type.Object({
 	),
 	task: Type.Optional(Type.String({ description: "Task to delegate (for single mode)" })),
 	tasks: Type.Optional(
-		Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" }),
+		Type.Array(TaskItem, {
+			description: "Array of {agent, task} for parallel execution",
+			maxItems: MAX_CONFIGURABLE_PARALLEL_TASKS,
+		}),
 	),
 	chain: Type.Optional(
 		Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" }),
 	),
 	aggregator: Type.Optional(AggregatorItem),
+	panel: Type.Optional(PanelItem),
+	workflow: Type.Optional(
+		Type.Object(
+			{
+				id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+				honorAdmission: Type.Optional(
+					Type.Boolean({
+						description:
+							"Opt in to declining workflow tasks whose explicit audit metadata recommends parent-owned work or abstention.",
+					}),
+				),
+				tasks: Type.Array(WorkflowTaskItem, {
+					minItems: 1,
+					maxItems: MAX_CONFIGURABLE_PARALLEL_TASKS,
+				}),
+			},
+			{ additionalProperties: false },
+		),
+	),
 	agentScope: Type.Optional(AgentScopeSchema),
 	confirmProjectAgents: Type.Optional(
 		Type.Boolean({
@@ -80,7 +246,17 @@ export const SubagentParams = Type.Object({
 		Type.String({ description: "Working directory for the agent process (single mode)" }),
 	),
 	timeoutMs: Type.Optional(TimeoutMs),
+	totalTimeoutMs: Type.Optional(
+		Type.Number({
+			description:
+				"Overall blocking-workflow deadline in milliseconds, including queued work, workflow tasks, panel phases, chain steps, and fan-in.",
+			minimum: 1,
+			maximum: MAX_SUBAGENT_TIMEOUT_MS,
+		}),
+	),
+	...TurnLimitFields,
 	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	...ContractFields,
 });
 
 export type SubagentParams = Static<typeof SubagentParams>;

package/src/persistence.ts

@@ -2,11 +2,22 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { projectAgentRecords } from "./agent-projection.js";
 import { isThinkingLevel } from "./agents.js";
+import { isCapabilityGrant, revokeCapabilityGrant } from "./capability-grant.js";
 import { redactPrivateText } from "./context.js";
+import { normalizeDelegationContract } from "./delegation-contract.js";
+import { copyExecutionPlan, isExecutionPlan } from "./execution-plan.js";
+import { MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
 import type { ManagedAgent } from "./registry.js";
+import { parseAnyStructuredSubagentResult, SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
+import { isSemanticSnapshot } from "./semantic-snapshot.js";
+import { resolveStatefulLimits } from "./stateful-limits.js";
+import { copyTurnTerminationReport, type TurnTerminationReport } from "./timeout-checkpoint.js";
+import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 
 const STATE_VERSION = 2;
+const DEFAULT_STATEFUL_LIMITS = resolveStatefulLimits();
 const MAX_STATE_BYTES = 1024 * 1024;
 
 interface StoredState {
@@ -35,7 +46,7 @@ export class AgentPersistence {
 		if (!Number.isFinite(retentionMs)) {
 			throw new Error("Subagent retentionDays is too large");
 		}
-		const maxStoredAgents = options.maxStoredAgents ?? 50;
+		const maxStoredAgents = options.maxStoredAgents ?? DEFAULT_STATEFUL_LIMITS.maxStoredAgents;
 		if (!Number.isSafeInteger(maxStoredAgents) || maxStoredAgents < 1) {
 			throw new Error("Subagent maxStoredAgents must be a positive safe integer");
 		}
@@ -54,10 +65,10 @@ export class AgentPersistence {
 			const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf8")) as unknown;
 			if (!isStoredState(parsed)) throw new Error("unsupported or malformed state");
 			const cutoff = Date.now() - this.retentionMs;
-			return parsed.agents
-				.filter((agent) => agent.updatedAt >= cutoff && agent.state !== "closed")
-				.slice(-this.maxStoredAgents)
-				.map(sanitizeAgent);
+			return projectAgentRecords(
+				parsed.agents.filter((agent) => agent.updatedAt >= cutoff && agent.state !== "closed"),
+				{ maxAgents: this.maxStoredAgents },
+			).map(sanitizeAgent);
 		} catch {
 			this.quarantine();
 			return [];
@@ -69,7 +80,9 @@ export class AgentPersistence {
 		const eligible = agents.filter(
 			(agent) => agent.state !== "closed" && agent.updatedAt >= cutoff,
 		);
-		const records = selectAgentsForPersistence(eligible, this.maxStoredAgents).map(sanitizeAgent);
+		const records = projectAgentRecords(eligible, {
+			maxAgents: this.maxStoredAgents,
+		}).map(sanitizeAgent);
 		const state: StoredState = { version: STATE_VERSION, updatedAt: Date.now(), agents: records };
 		let content = `${JSON.stringify(state, null, "\t")}\n`;
 		while (Buffer.byteLength(content, "utf8") > MAX_STATE_BYTES && state.agents.length > 0) {
@@ -100,30 +113,6 @@ export class AgentPersistence {
 	}
 }
 
-function selectAgentsForPersistence(
-	agents: readonly ManagedAgent[],
-	maxAgents: number,
-): ManagedAgent[] {
-	const byId = new Map(agents.map((agent) => [agent.id, agent]));
-	const selected = new Map<string, ManagedAgent>();
-	const newestFirst = [...agents].sort((left, right) => right.updatedAt - left.updatedAt);
-	for (const agent of newestFirst) {
-		const chain: ManagedAgent[] = [];
-		let current: ManagedAgent | undefined = agent;
-		const seen = new Set<string>();
-		while (current && !seen.has(current.id)) {
-			seen.add(current.id);
-			chain.unshift(current);
-			current = current.parentId ? byId.get(current.parentId) : undefined;
-		}
-		if (current || (agent.parentId && chain[0].parentId)) continue;
-		const missing = chain.filter((candidate) => !selected.has(candidate.id));
-		if (selected.size + missing.length > maxAgents) continue;
-		for (const candidate of missing) selected.set(candidate.id, candidate);
-	}
-	return agents.filter((agent) => selected.has(agent.id));
-}
-
 function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
 	return {
 		...agent,
@@ -135,19 +124,63 @@ function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
 			recipientId: agent.id,
 			content: redactPrivateText(message.content),
 		})),
-		state: "idle",
+		state: agent.state === "running" || agent.state === "starting" ? "interrupted" : agent.state,
 		currentTask: undefined,
+		currentTimeoutMs: undefined,
+		currentIdleTimeoutMs: undefined,
+		currentMaxTurns: undefined,
+		currentMaxToolCalls: undefined,
 		currentMailboxMessageIds: undefined,
+		telemetry: undefined,
+		contract: normalizeDelegationContract(agent.contract),
+		structuredResult:
+			agent.structuredResult && agent.resultFormat
+				? parseAnyStructuredSubagentResult(
+						JSON.stringify(agent.structuredResult),
+						agent.resultFormat,
+					)
+				: undefined,
+		executionPlan: agent.executionPlan ? copyExecutionPlan(agent.executionPlan) : undefined,
+		capabilityGrant: agent.capabilityGrant
+			? agent.capabilityGrant.state === "active"
+				? revokeCapabilityGrant(agent.capabilityGrant, "persistence-boundary", Date.now())
+				: structuredClone(agent.capabilityGrant)
+			: undefined,
+		semanticSnapshot: agent.semanticSnapshot ? structuredClone(agent.semanticSnapshot) : undefined,
+		semanticCompatibility: agent.semanticCompatibility
+			? structuredClone(agent.semanticCompatibility)
+			: undefined,
+		termination: agent.termination ? sanitizeTermination(agent.termination) : undefined,
 		context: agent.context ? redactPrivateText(agent.context) : undefined,
 		error: agent.error ? redactPrivateText(agent.error) : undefined,
 		history: agent.history.map((turn) => ({
 			...turn,
 			task: redactPrivateText(turn.task),
 			output: redactPrivateText(turn.output),
+			termination: turn.termination ? sanitizeTermination(turn.termination) : undefined,
 		})),
 	};
 }
 
+function sanitizeTermination(report: TurnTerminationReport): TurnTerminationReport {
+	const copy = copyTurnTerminationReport(report);
+	copy.checkpoint.task = redactPrivateText(copy.checkpoint.task);
+	copy.checkpoint.partialOutput = copy.checkpoint.partialOutput
+		? redactPrivateText(copy.checkpoint.partialOutput)
+		: undefined;
+	copy.checkpoint.assistantNotes = copy.checkpoint.assistantNotes.map(redactPrivateText);
+	copy.checkpoint.completedTools = copy.checkpoint.completedTools.map((item) => ({
+		...item,
+		toolName: redactPrivateText(item.toolName),
+		output: redactPrivateText(item.output),
+	}));
+	copy.checkpoint.changedFiles = copy.checkpoint.changedFiles.map(redactPrivateText);
+	copy.finalization.error = copy.finalization.error
+		? redactPrivateText(copy.finalization.error)
+		: undefined;
+	return copy;
+}
+
 function isStoredState(value: unknown): value is StoredState {
 	if (!value || typeof value !== "object") return false;
 	const state = value as { version?: unknown; agents?: unknown };
@@ -167,6 +200,34 @@ function isStoredState(value: unknown): value is StoredState {
 			Number.isFinite(record.updatedAt) &&
 			(record.parentId === undefined || typeof record.parentId === "string") &&
 			(record.thinkingLevel === undefined || isThinkingLevel(record.thinkingLevel)) &&
+			(record.timeoutMs === undefined || isTurnTimeout(record.timeoutMs)) &&
+			(record.idleTimeoutMs === undefined || isTurnTimeout(record.idleTimeoutMs)) &&
+			(record.maxTurns === undefined || isPositiveBounded(record.maxTurns, MAX_SUBAGENT_TURNS)) &&
+			(record.maxToolCalls === undefined ||
+				isPositiveBounded(record.maxToolCalls, MAX_SUBAGENT_TOOL_CALLS)) &&
+			(record.termination === undefined || isTerminationReport(record.termination)) &&
+			(record.contextTurns === undefined || isNonNegativeInteger(record.contextTurns)) &&
+			(record.contextBytes === undefined || isNonNegativeInteger(record.contextBytes)) &&
+			(record.spawnIdempotencyKey === undefined ||
+				(typeof record.spawnIdempotencyKey === "string" &&
+					record.spawnIdempotencyKey.length > 0 &&
+					record.spawnIdempotencyKey.length <= 256)) &&
+			(record.spawnRequestHash === undefined || isSha256(record.spawnRequestHash)) &&
+			(record.contract === undefined ||
+				normalizeDelegationContract(record.contract) !== undefined) &&
+			(record.resultFormat === undefined ||
+				SUBAGENT_RESULT_FORMATS.includes(record.resultFormat)) &&
+			(record.structuredResult === undefined ||
+				(record.resultFormat !== undefined &&
+					parseAnyStructuredSubagentResult(
+						JSON.stringify(record.structuredResult),
+						record.resultFormat,
+					) !== undefined)) &&
+			(record.executionPlan === undefined || isExecutionPlan(record.executionPlan)) &&
+			(record.capabilityGrant === undefined || isCapabilityGrant(record.capabilityGrant)) &&
+			(record.semanticSnapshot === undefined || isSemanticSnapshot(record.semanticSnapshot)) &&
+			(record.semanticCompatibility === undefined ||
+				isSemanticCompatibility(record.semanticCompatibility)) &&
 			(record.workspaceMode === undefined || record.workspaceMode === "worktree") &&
 			(record.target === undefined || isTargetPolicyAudit(record.target)) &&
 			(record.children === undefined ||
@@ -180,6 +241,94 @@ function isStoredState(value: unknown): value is StoredState {
 	});
 }
 
+function isSemanticCompatibility(value: unknown): boolean {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const compatibility = value as Record<string, unknown>;
+	return (
+		["compatible", "warning", "needs-revalidation", "rejected"].includes(
+			String(compatibility.status),
+		) &&
+		Array.isArray(compatibility.changedComponents) &&
+		compatibility.changedComponents.every((item) => typeof item === "string")
+	);
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isTurnTimeout(value: unknown): value is number {
+	return (
+		typeof value === "number" &&
+		Number.isSafeInteger(value) &&
+		value >= 1 &&
+		value <= MAX_SUBAGENT_TIMEOUT_MS
+	);
+}
+
+function isPositiveBounded(value: unknown, maximum: number): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= maximum;
+}
+
+function isTerminationReport(value: unknown): value is TurnTerminationReport {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const report = value as Record<string, unknown>;
+	if (
+		report.version !== "pi-subagents:termination:v1" ||
+		![
+			"work_timeout",
+			"idle_timeout",
+			"turn_limit",
+			"tool_call_limit",
+			"orchestration_timeout",
+		].includes(String(report.reason)) ||
+		!isPositiveBounded(report.limit, MAX_SUBAGENT_TIMEOUT_MS)
+	) {
+		return false;
+	}
+	const checkpoint = report.checkpoint;
+	const finalization = report.finalization;
+	if (!checkpoint || typeof checkpoint !== "object" || Array.isArray(checkpoint)) return false;
+	if (!finalization || typeof finalization !== "object" || Array.isArray(finalization))
+		return false;
+	const checkpointValue = checkpoint as Record<string, unknown>;
+	const finalizationValue = finalization as Record<string, unknown>;
+	return (
+		checkpointValue.version === "pi-subagents:checkpoint:v1" &&
+		typeof checkpointValue.task === "string" &&
+		(checkpointValue.partialOutput === undefined ||
+			typeof checkpointValue.partialOutput === "string") &&
+		Array.isArray(checkpointValue.assistantNotes) &&
+		checkpointValue.assistantNotes.every((item) => typeof item === "string") &&
+		Array.isArray(checkpointValue.completedTools) &&
+		checkpointValue.completedTools.every(isCompletedToolEvidence) &&
+		Array.isArray(checkpointValue.changedFiles) &&
+		checkpointValue.changedFiles.every((item) => typeof item === "string") &&
+		typeof checkpointValue.sideEffectsMayHaveOccurred === "boolean" &&
+		typeof checkpointValue.truncated === "boolean" &&
+		typeof finalizationValue.attempted === "boolean" &&
+		["completed", "failed", "timed_out", "skipped"].includes(String(finalizationValue.status)) &&
+		typeof finalizationValue.durationMs === "number" &&
+		Number.isFinite(finalizationValue.durationMs) &&
+		finalizationValue.durationMs >= 0 &&
+		(finalizationValue.error === undefined || typeof finalizationValue.error === "string")
+	);
+}
+
+function isCompletedToolEvidence(value: unknown): boolean {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const item = value as Record<string, unknown>;
+	return (
+		typeof item.toolName === "string" &&
+		typeof item.output === "string" &&
+		typeof item.isError === "boolean"
+	);
+}
+
+function isSha256(value: unknown): value is string {
+	return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+}
+
 function isTargetPolicyAudit(value: unknown): boolean {
 	if (!value || typeof value !== "object") return false;
 	const target = value as Record<string, unknown>;
@@ -218,7 +367,8 @@ function isAgentTurn(value: unknown): boolean {
 		typeof turn.completedAt === "number" &&
 		Number.isFinite(turn.completedAt) &&
 		typeof turn.exitCode === "number" &&
-		Number.isFinite(turn.exitCode)
+		Number.isFinite(turn.exitCode) &&
+		(turn.termination === undefined || isTerminationReport(turn.termination))
 	);
 }
 

package/src/prompt-resources.ts

@@ -0,0 +1,38 @@
+import {
+	DefaultResourceLoader,
+	getAgentDir,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { assertPiPromptSourcesAreReadableFiles } from "./prompt-source-safety.js";
+
+export interface PiPromptResources {
+	systemPrompt?: string;
+	appendSystemPromptPaths: string[];
+}
+
+/** Resolve Pi-owned prompt files without loading target packages, extensions, or settings. */
+export async function resolvePiPromptResources(
+	cwd: string,
+	projectTrusted: boolean,
+	agentDir = getAgentDir(),
+): Promise<PiPromptResources> {
+	assertPiPromptSourcesAreReadableFiles(cwd, agentDir, projectTrusted, [
+		"SYSTEM.md",
+		"APPEND_SYSTEM.md",
+	]);
+	const loader = new DefaultResourceLoader({
+		cwd,
+		agentDir,
+		settingsManager: SettingsManager.inMemory({}, { projectTrusted }),
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+		noContextFiles: true,
+	});
+	await loader.reload();
+	return {
+		systemPrompt: loader.getSystemPrompt(),
+		appendSystemPromptPaths: loader.getAppendSystemPromptSources().map((source) => source.path),
+	};
+}