pi-subagents 0.49.0 → 0.51.0

package/src/api/external-runs.ts

@@ -1,129 +1,219 @@
-export const EXTERNAL_RUN_REGISTRY_VERSION = 1;
-export const EXTERNAL_RUN_REGISTRY_KEY = "pi-subagents.external-runs.v1";
+import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text.ts";
 
-const MAX_PROVIDERS = 100;
-const MAX_RUNS_PER_PROVIDER = 10_000;
-const MAX_TEXT_LENGTH = 4_096;
+export const EXTERNAL_RUN_REGISTRY_VERSION = 2;
+export const EXTERNAL_RUN_REGISTRY_KEY = "pi-subagents.external-runs.v2";
 
-export type ExternalRunState = "running" | "completed" | "failed" | "stopped";
-export type ExternalRunCompletionReason = "exit" | "timeout" | "user-kill" | "auto-close-quiet" | "crash" | "unknown";
+export const EXTERNAL_RUN_LIMITS = {
+	maxCachedRuns: 100,
+	maxSnapshotRuns: 20,
+	maxIdentityLength: 160,
+	/**
+	 * A Pi session id is the session file path, which routinely exceeds a short
+	 * identity budget in nested worktrees, so it is bounded like the other paths.
+	 */
+	maxSessionIdLength: 4_096,
+	maxTextLength: 160,
+	maxPreviewLength: 4_096,
+	maxPathLength: 4_096,
+	maxSerializedBytes: 32 * 1_024,
+} as const;
 
-/** An observational record for work owned by another runtime. */
+export type ExternalRunState = "queued" | "running" | "completed" | "failed" | "stopped";
+
+/** A display-only record for work owned by another extension or runtime. */
 export interface ExternalRun {
 	id: string;
 	sessionId: string;
 	source: string;
+	label: string;
 	state: ExternalRunState;
-	command?: string;
-	cwd?: string;
-	isolationPath?: string;
-	owner?: string;
-	completionReason?: ExternalRunCompletionReason;
+	startedAt: number;
+	updatedAt?: number;
+	endedAt?: number;
+	currentAction?: string;
+	preview?: string;
 	reportPath?: string;
-	startedAt?: number;
-	completedAt?: number;
-	exitCode?: number | null;
-	residualRisks?: string[];
+	transcriptPath?: string;
 }
 
-export interface ExternalRunProvider {
-	name: string;
-	listExternalRuns(): readonly ExternalRun[];
-}
+export type ExternalRunUpdate = Partial<Omit<ExternalRun, "id" | "sessionId" | "source">>;
 
-export interface RegisteredExternalRun extends ExternalRun {
-	provider: string;
+export interface ExternalRunSnapshotOptions {
+	onMalformedRecord?: (message: string) => void;
+	ignoreMalformed?: boolean;
 }
 
 interface ExternalRunRegistry {
 	version: typeof EXTERNAL_RUN_REGISTRY_VERSION;
-	providers: Map<string, ExternalRunProvider>;
+	runs: Map<string, ExternalRun>;
 }
 
+const RUN_FIELDS = new Set([
+	"id",
+	"sessionId",
+	"source",
+	"label",
+	"state",
+	"startedAt",
+	"updatedAt",
+	"endedAt",
+	"currentAction",
+	"preview",
+	"reportPath",
+	"transcriptPath",
+]);
+const UPDATE_FIELDS = new Set([...RUN_FIELDS].filter((field) => field !== "id" && field !== "sessionId" && field !== "source"));
+
 function registry(): ExternalRunRegistry {
 	const key = Symbol.for(EXTERNAL_RUN_REGISTRY_KEY);
 	const target = globalThis as Record<PropertyKey, unknown>;
 	const existing = target[key];
 	if (existing === undefined) {
-		const created: ExternalRunRegistry = { version: EXTERNAL_RUN_REGISTRY_VERSION, providers: new Map() };
+		const created: ExternalRunRegistry = { version: EXTERNAL_RUN_REGISTRY_VERSION, runs: new Map() };
 		target[key] = created;
 		return created;
 	}
 	if (!existing || typeof existing !== "object" || Array.isArray(existing)) throw new Error(`Malformed external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
 	const candidate = existing as Partial<ExternalRunRegistry>;
-	if (candidate.version !== EXTERNAL_RUN_REGISTRY_VERSION || !(candidate.providers instanceof Map)) throw new Error(`Unsupported external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
+	if (candidate.version !== EXTERNAL_RUN_REGISTRY_VERSION || !(candidate.runs instanceof Map)) throw new Error(`Unsupported external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
 	return candidate as ExternalRunRegistry;
 }
 
-function text(value: unknown, field: string, required = false): string | undefined {
-	if (value === undefined && !required) return undefined;
+function inputObject(value: unknown, field: string, allowed: Set<string>): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${field} must be an object.`);
+	const input = value as Record<string, unknown>;
+	const unknown = Object.keys(input).filter((key) => !allowed.has(key));
+	if (unknown.length) throw new Error(`${field} has unknown fields: ${unknown.join(", ")}.`);
+	return input;
+}
+
+function identity(value: unknown, field: string, maxLength: number = EXTERNAL_RUN_LIMITS.maxIdentityLength): string {
 	if (typeof value !== "string" || value.length === 0 || value.trim() !== value || value.includes("\0")) throw new Error(`${field} must be a non-empty trimmed string without NUL characters.`);
-	if (value.length > MAX_TEXT_LENGTH) throw new Error(`${field} must be at most ${MAX_TEXT_LENGTH} characters.`);
+	if (value.length > maxLength) throw new Error(`${field} must be at most ${maxLength} characters.`);
+	const safe = sanitizeDisplayText(value);
+	if (!safe || safe !== value) throw new Error(`${field} must contain only display-safe text.`);
 	return value;
 }
 
-function timestamp(value: unknown, field: string): number | undefined {
-	if (value === undefined) return undefined;
-	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${field} must be a non-negative finite number.`);
+function displayText(value: unknown, field: string, maxLength: number): string | undefined;
+function displayText(value: unknown, field: string, maxLength: number, required: true): string;
+function displayText(value: unknown, field: string, maxLength: number, required = false): string | undefined {
+	if (value === undefined && !required) return undefined;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${field} must be a non-empty string.`);
+	const safe = sanitizeDisplayText(value.slice(0, Math.max(maxLength * 4, maxLength)));
+	if (!safe) throw new Error(`${field} must contain displayable text.`);
+	return truncateDisplayText(safe, maxLength);
+}
+
+function timestamp(value: unknown, field: string): number | undefined;
+function timestamp(value: unknown, field: string, required: true): number;
+function timestamp(value: unknown, field: string, required = false): number | undefined {
+	if (value === undefined && !required) return undefined;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 8_640_000_000_000_000) throw new Error(`${field} must be a non-negative safe timestamp.`);
 	return value;
 }
 
-function validateRun(value: unknown, provider: string, index: number): ExternalRun {
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`External-run provider '${provider}' item ${index} must be an object.`);
-	const run = value as Record<string, unknown>;
-	const fields = new Set(["id", "sessionId", "source", "state", "command", "cwd", "isolationPath", "owner", "completionReason", "reportPath", "startedAt", "completedAt", "exitCode", "residualRisks"]);
-	const unknown = Object.keys(run).filter((key) => !fields.has(key));
-	if (unknown.length) throw new Error(`External-run provider '${provider}' item ${index} has unknown fields: ${unknown.join(", ")}.`);
-	if (!["running", "completed", "failed", "stopped"].includes(run.state as string)) throw new Error(`External-run provider '${provider}' item ${index} state is invalid.`);
-	if (run.completionReason !== undefined && !["exit", "timeout", "user-kill", "auto-close-quiet", "crash", "unknown"].includes(run.completionReason as string)) throw new Error(`External-run provider '${provider}' item ${index} completionReason is invalid.`);
-	if (run.exitCode !== undefined && run.exitCode !== null && (!Number.isInteger(run.exitCode) || !Number.isFinite(run.exitCode))) throw new Error(`External-run provider '${provider}' item ${index} exitCode must be an integer or null.`);
-	if (run.residualRisks !== undefined && (!Array.isArray(run.residualRisks) || run.residualRisks.some((risk, riskIndex) => text(risk, `External-run provider '${provider}' item ${index} residualRisks[${riskIndex}]`, true) === undefined))) throw new Error(`External-run provider '${provider}' item ${index} residualRisks must be an array of strings.`);
+function state(value: unknown, field: string): ExternalRunState {
+	if (value === "queued" || value === "running" || value === "completed" || value === "failed" || value === "stopped") return value;
+	throw new Error(`${field} is invalid.`);
+}
+
+function validateRun(value: unknown): ExternalRun {
+	const run = inputObject(value, "External run", RUN_FIELDS);
+	const updatedAt = timestamp(run.updatedAt, "External run updatedAt");
+	const endedAt = timestamp(run.endedAt, "External run endedAt");
+	const currentAction = displayText(run.currentAction, "External run currentAction", EXTERNAL_RUN_LIMITS.maxTextLength);
+	const preview = displayText(run.preview, "External run preview", EXTERNAL_RUN_LIMITS.maxPreviewLength);
+	const reportPath = displayText(run.reportPath, "External run reportPath", EXTERNAL_RUN_LIMITS.maxPathLength);
+	const transcriptPath = displayText(run.transcriptPath, "External run transcriptPath", EXTERNAL_RUN_LIMITS.maxPathLength);
 	return {
-		id: text(run.id, `External-run provider '${provider}' item ${index} id`, true)!,
-		sessionId: text(run.sessionId, `External-run provider '${provider}' item ${index} sessionId`, true)!,
-		source: text(run.source, `External-run provider '${provider}' item ${index} source`, true)!,
-		state: run.state as ExternalRunState,
-		...(text(run.command, `External-run provider '${provider}' item ${index} command`) !== undefined ? { command: text(run.command, `External-run provider '${provider}' item ${index} command`) } : {}),
-		...(text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) !== undefined ? { cwd: text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) } : {}),
-		...(text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) !== undefined ? { isolationPath: text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) } : {}),
-		...(text(run.owner, `External-run provider '${provider}' item ${index} owner`) !== undefined ? { owner: text(run.owner, `External-run provider '${provider}' item ${index} owner`) } : {}),
-		...(run.completionReason !== undefined ? { completionReason: run.completionReason as ExternalRunCompletionReason } : {}),
-		...(text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) !== undefined ? { reportPath: text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) } : {}),
-		...(timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) !== undefined ? { startedAt: timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) } : {}),
-		...(timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) !== undefined ? { completedAt: timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) } : {}),
-		...(run.exitCode !== undefined ? { exitCode: run.exitCode as number | null } : {}),
-		...(run.residualRisks !== undefined ? { residualRisks: [...run.residualRisks] as string[] } : {}),
+		id: identity(run.id, "External run id"),
+		sessionId: identity(run.sessionId, "External run sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength),
+		source: displayText(run.source, "External run source", EXTERNAL_RUN_LIMITS.maxTextLength, true),
+		label: displayText(run.label, "External run label", EXTERNAL_RUN_LIMITS.maxTextLength, true),
+		state: state(run.state, "External run state"),
+		startedAt: timestamp(run.startedAt, "External run startedAt", true),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+		...(endedAt !== undefined ? { endedAt } : {}),
+		...(currentAction ? { currentAction } : {}),
+		...(preview ? { preview } : {}),
+		...(reportPath ? { reportPath } : {}),
+		...(transcriptPath ? { transcriptPath } : {}),
 	};
 }
 
-/** Register an observational provider. pi-subagents never starts, stops, or steers these processes. */
-export function registerExternalRunProvider(provider: ExternalRunProvider): () => void {
-	if (!provider || typeof provider !== "object" || Array.isArray(provider) || Object.keys(provider).some((key) => key !== "name" && key !== "listExternalRuns")) throw new Error("External-run provider must contain only name and listExternalRuns.");
-	const name = text(provider.name, "External-run provider name", true)!;
-	if (typeof provider.listExternalRuns !== "function") throw new Error(`External-run provider '${name}' must expose listExternalRuns().`);
+function key(sessionId: string, id: string): string {
+	return `${sessionId}\0${id}`;
+}
+
+function clone(run: ExternalRun): ExternalRun {
+	return { ...run };
+}
+
+/** Register one current-session external job. pi-subagents never controls the job. */
+export function registerExternalRun(input: ExternalRun): ExternalRun {
+	const run = validateRun(input);
+	const current = registry();
+	const runKey = key(run.sessionId, run.id);
+	if (current.runs.has(runKey)) throw new Error(`External run '${run.id}' is already registered for session '${run.sessionId}'.`);
+	if (current.runs.size >= EXTERNAL_RUN_LIMITS.maxCachedRuns) throw new Error(`External-run registry supports at most ${EXTERNAL_RUN_LIMITS.maxCachedRuns} cached runs.`);
+	current.runs.set(runKey, run);
+	return clone(run);
+}
+
+/** Update display fields for a registered external job without changing its identity or owner. */
+export function updateExternalRun(sessionId: string, id: string, update: ExternalRunUpdate): ExternalRun {
+	const safeSessionId = identity(sessionId, "External run sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength);
+	const safeId = identity(id, "External run id");
+	const patch = inputObject(update, "External run update", UPDATE_FIELDS);
+	const current = registry();
+	const runKey = key(safeSessionId, safeId);
+	const previous = current.runs.get(runKey);
+	if (!previous) throw new Error(`External run '${safeId}' is not registered for session '${safeSessionId}'.`);
+	const next = validateRun({ ...previous, ...patch });
+	current.runs.set(runKey, next);
+	return clone(next);
+}
+
+/** Remove a cached external job. The caller remains responsible for its process and artifacts. */
+export function unregisterExternalRun(sessionId: string, id: string): boolean {
+	return registry().runs.delete(key(identity(sessionId, "External run sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength), identity(id, "External run id")));
+}
+
+function snapshotBytes(runs: readonly ExternalRun[]): number {
+	return Buffer.byteLength(JSON.stringify(runs), "utf8");
+}
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/** Read a bounded cached snapshot for one Pi session. This never invokes third-party code. */
+export function snapshotExternalRuns(sessionId: string, options: ExternalRunSnapshotOptions = {}): readonly ExternalRun[] {
+	const safeSessionId = identity(sessionId, "External-run snapshot sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength);
 	const current = registry();
-	if (!current.providers.has(name) && current.providers.size >= MAX_PROVIDERS) throw new Error(`External-run registry supports at most ${MAX_PROVIDERS} providers.`);
-	current.providers.set(name, provider);
-	return () => { if (current.providers.get(name) === provider) current.providers.delete(name); };
-}
-
-/** Snapshot records for one Pi session. Records are read-only observations of foreign process ownership. */
-export function snapshotExternalRuns(sessionId: string): readonly RegisteredExternalRun[] {
-	text(sessionId, "External-run snapshot sessionId", true);
-	const records: RegisteredExternalRun[] = [];
-	const identities = new Set<string>();
-	for (const [name, provider] of registry().providers) {
-		if (provider.name !== name) throw new Error(`External-run registry key '${name}' does not match provider name '${provider.name}'.`);
-		const runs = provider.listExternalRuns();
-		if (!Array.isArray(runs)) throw new Error(`External-run provider '${name}' listExternalRuns() must return an array.`);
-		if (runs.length > MAX_RUNS_PER_PROVIDER) throw new Error(`External-run provider '${name}' returned more than ${MAX_RUNS_PER_PROVIDER} runs.`);
-		runs.forEach((value, index) => {
-			const run = validateRun(value, name, index);
-			const identity = `${name}\0${run.sessionId}\0${run.id}`;
-			if (identities.has(identity)) throw new Error(`External-run provider '${name}' returned duplicate run '${run.id}' for session '${run.sessionId}'.`);
-			identities.add(identity);
-			if (run.sessionId === sessionId) records.push({ provider: name, ...run });
-		});
+	const runs: ExternalRun[] = [];
+	for (const [cacheKey, value] of current.runs.entries()) {
+		try {
+			const run = validateRun(value);
+			if (run.sessionId === safeSessionId) runs.push(run);
+		} catch (error) {
+			const message = `Malformed cached external run '${cacheKey}': ${getErrorMessage(error)}`;
+			if (!options.ignoreMalformed) throw new Error(message, { cause: error instanceof Error ? error : undefined });
+			current.runs.delete(cacheKey);
+			options.onMalformedRecord?.(message);
+		}
 	}
-	return records;
+	runs.sort((left, right) => {
+		const leftActive = left.state === "queued" || left.state === "running";
+		const rightActive = right.state === "queued" || right.state === "running";
+		if (leftActive !== rightActive) return leftActive ? -1 : 1;
+		return (right.updatedAt ?? right.endedAt ?? right.startedAt) - (left.updatedAt ?? left.endedAt ?? left.startedAt) || left.id.localeCompare(right.id);
+	});
+	const snapshot = runs.slice(0, EXTERNAL_RUN_LIMITS.maxSnapshotRuns).map(clone);
+	while (snapshot.length > 0 && snapshotBytes(snapshot) > EXTERNAL_RUN_LIMITS.maxSerializedBytes) snapshot.pop();
+	return snapshot;
 }
+
+/** Alias for callers that prefer list terminology. */
+export const listExternalRuns = snapshotExternalRuns;

package/src/api/preflight.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { discoverAgents, discoverAgentsAll, resolveAgentName, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
+import { discoverAgents, discoverAgentsAll, findBlockingAgentDiagnostic, resolveAgentName, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
 import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
 import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
@@ -17,9 +17,12 @@ import { appendTurnBudgetSystemPrompt } from "../runs/shared/turn-budget.ts";
 import type { ResolvedTurnBudget } from "../shared/types.ts";
 import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
 import { resolveStepBehavior } from "../shared/settings.ts";
+import { canPreferForkFromSnapshot, resolveSubagentLaunchContext } from "../shared/fork-context.ts";
+import { loadConfig } from "../extension/config.ts";
 import { agentDefinitionDigest, AGENT_DEFINITION_PROJECTION_VERSION, launchBindingDigest } from "../shared/launch-contract.ts";
 import { DIRS, TEMP_ROOT_DIR } from "../shared/types.ts";
 import { processTerminalCandidatePath, processTerminalPath } from "../runs/background/process-terminal.ts";
+import { resultFilePath } from "../runs/background/result-files.ts";
 import { nestedResultsPath } from "../runs/shared/nested-events.ts";
 
 export const SUBAGENT_LAUNCH_CONTRACT_VERSION = 2 as const;
@@ -59,6 +62,8 @@ export interface SubagentLaunchContractInput {
 	artifacts?: boolean;
 	artifactDir?: ArtifactDirPreference;
 	parentSessionFile?: string | null;
+	/** Current parent leaf required before an implicit `defaultContext: fork` stays `fork`. */
+	parentLeafId?: string | null;
 	sessionRoot?: string;
 	sessionDir?: string;
 	runId?: string;
@@ -189,6 +194,18 @@ function normalizeAvailableModels(models: SubagentLaunchContractInput["available
 	return (models ?? []).map((model) => ({ ...model, fullId: model.fullId ?? `${model.provider}/${model.id}` }));
 }
 
+function resolveLaunchContractContext(input: SubagentLaunchContractInput, agent: AgentConfig): "fresh" | "fork" {
+	return resolveSubagentLaunchContext({
+		explicitContext: input.context,
+		agentDefaultContext: agent.defaultContext,
+		defaultSubagentContext: loadConfig().defaultSubagentContext,
+		canUseImplicitFork: canPreferForkFromSnapshot({
+			parentSessionFile: input.parentSessionFile,
+			leafId: input.parentLeafId,
+		}),
+	});
+}
+
 function candidateList(inputAgent: string, selected: AgentConfig | undefined, cwd: string): SubagentLaunchContractAgentCandidate[] {
 	const all = discoverAgentsAll(cwd);
 	return [...all.builtin, ...all.package, ...all.user, ...all.project]
@@ -221,12 +238,17 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 	if (input.artifactDir !== undefined && input.artifactDir !== "project" && input.artifactDir !== "session" && input.artifactDir !== "temp") {
 		return { ok: false, code: "invalid_artifact_dir", message: `Unsupported artifactDir '${String(input.artifactDir)}'; expected 'project', 'session', or 'temp'.`, diagnostics };
 	}
-	if (input.context === "fork") {
-		diagnostics.push({ code: "host_required", severity: "host-required", message: "Exact fork session branching and fork-thinking downgrade checks require Pi host session and model-registry snapshots." });
-	}
 	const scope = resolveExecutionAgentScope(input.agentScope);
 	const discovered = discoverAgents(effectiveCwd, scope);
 	const resolvedAgent = resolveAgentName(input.agent, discovered.agents);
+	const ambiguousCandidates = resolvedAgent.error
+		? discovered.agents.filter((agent) => resolveAgentName(input.agent, [agent]).agent)
+		: resolvedAgent.agent;
+	const invalidAgent = findBlockingAgentDiagnostic(input.agent, ambiguousCandidates, discovered.agentDiagnostics);
+	if (invalidAgent) {
+		const message = `Agent '${input.agent}' has invalid configuration: ${invalidAgent.error}`;
+		return { ok: false, code: "missing_agent", message, diagnostics: [{ code: "missing_agent", severity: "error", message }] };
+	}
 	if (resolvedAgent.error) {
 		return { ok: false, code: "ambiguous_agent", message: resolvedAgent.error, diagnostics };
 	}
@@ -234,6 +256,10 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		return { ok: false, code: "missing_agent", message: `Unknown agent: ${input.agent}`, diagnostics };
 	}
 	const agent = resolvedAgent.agent;
+	const context = resolveLaunchContractContext(input, agent);
+	if (context === "fork") {
+		diagnostics.push({ code: "host_required", severity: "host-required", message: "Exact fork session branching and fork-thinking downgrade checks require Pi host session and model-registry snapshots." });
+	}
 	const effectiveCapabilityCeiling = intersectSubagentCapabilityCeilings(input.capabilityCeiling, input.inheritedCapabilityCeiling);
 	const restrictionMessage = capabilityCeilingAgentRestrictionMessage(agent.name, effectiveCapabilityCeiling);
 	if (restrictionMessage) return { ok: false, code: "restricted_agent", message: restrictionMessage, diagnostics };
@@ -259,13 +285,18 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 	}
 	if (resolvedSkills.missing.length > 0) diagnostics.push({ code: "missing_skill", severity: "error", message: `Missing skills: ${resolvedSkills.missing.join(", ")}` });
 
+	const externalRunner = agent.runner?.type === "external-cli" || agent.runner?.type === "external-job";
 	const availableModels = normalizeAvailableModels(input.availableModels);
 	const preferredProvider = input.preferredProvider ?? input.parentModel?.provider;
-	const primaryModel = resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: discovered.modelScope });
+	const primaryModel = externalRunner
+		? undefined
+		: resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: discovered.modelScope });
 	const effectiveThinkingConfig = input.thinking !== undefined ? input.thinking : agent.thinking;
-	const model = applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
-	const modelCandidates = buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, { scope: discovered.modelScope })
-		.map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
+	const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
+	const modelCandidates = externalRunner
+		? []
+		: buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, { scope: discovered.modelScope })
+			.map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
 	let toolPlan: PiLaunchToolPlan;
 	try {
 		toolPlan = resolvePiLaunchToolPlan({
@@ -295,9 +326,9 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		: path.join(DIRS.async, runId);
 	const lifecycleResultPath = input.nestedRootRunId
 		? nestedResultsPath(input.nestedRootRunId, runId)
-		: path.join(DIRS.results, `${runId}.json`);
+		: resultFilePath(DIRS.results, runId);
 	if (!sessionDir) diagnostics.push({ code: "host_required", severity: "host-required", message: "No sessionRoot/sessionDir was supplied; exact child session paths require the Pi host session-root policy." });
-	if (input.availableModels === undefined && (input.model || agent.model || input.parentModel)) {
+	if (!externalRunner && input.availableModels === undefined && (input.model || agent.model || input.parentModel)) {
 		diagnostics.push({ code: "host_required", severity: "host-required", message: "No availableModels snapshot was supplied; model resolution may differ from the active Pi host registry." });
 	}
 	if (resolvedSkills.missing.length > 0) {
@@ -329,7 +360,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 			definitionDigest,
 			shadowedCandidates,
 		},
-		context: input.context ?? agent.defaultContext ?? "fresh",
+		context,
 		...(model ? { model } : {}),
 		modelCandidates,
 		...(resolveEffectiveThinking(model, effectiveThinkingConfig) ? { thinking: resolveEffectiveThinking(model, effectiveThinkingConfig) } : {}),

package/src/api/shared-types.ts

@@ -9,6 +9,8 @@ export {
 	type ControlEvent,
 	type Details,
 	type ExecutionProjection,
+	type ExternalJobRunnerStatus,
+	type ExternalJobStatus,
 	type JsonSchemaObject,
 	type OutputMode,
 	type ReviewProjection,

package/src/extension/config.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { Key } from "@earendil-works/pi-tui";
 import { FLEET_KEYBINDING_ACTIONS, type ArtifactDirPreference, type ExtensionConfig } from "../shared/types.ts";
 import { validateMissionStoreConfig } from "../missions/store.ts";
 import { validateAuthorityPolicy } from "../policy/authority.ts";
@@ -9,6 +10,21 @@ import { validatePermissionConfig } from "../runs/shared/permissions.ts";
 
 const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
 const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
+const KEY_MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+const BASE_KEY_IDS = new Set([
+	..."abcdefghijklmnopqrstuvwxyz0123456789",
+	...Object.values(Key).flatMap((value) => typeof value === "string" ? [value.toLowerCase()] : []),
+]);
+
+function isValidKeyId(value: string): boolean {
+	if (value !== value.trim()) return false;
+	const parts = value.toLowerCase().split("+");
+	const base = parts.pop();
+	if (!base || !BASE_KEY_IDS.has(base)) return false;
+	return parts.length <= KEY_MODIFIERS.size
+		&& new Set(parts).size === parts.length
+		&& parts.every((modifier) => KEY_MODIFIERS.has(modifier));
+}
 
 export function resolveScheduledStoreRoot(value: string): string {
 	const expanded = value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
@@ -46,6 +62,18 @@ function validateArtifactConfig(value: unknown): void {
 	}
 }
 
+function validateOrcaProgressTabsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.orcaProgressTabs must be a JSON object");
+	const config = value as Record<string, unknown>;
+	for (const key of Object.keys(config)) {
+		if (key !== "enabled") throw new Error(`config.orcaProgressTabs.${key} is not supported`);
+	}
+	if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+		throw new Error("config.orcaProgressTabs.enabled must be a boolean");
+	}
+}
+
 function validateMainWindowRendererConfig(value: unknown): void {
 	if (value === undefined) return;
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.mainWindowRenderer must be a JSON object");
@@ -66,12 +94,16 @@ function validateMainWindowRendererConfig(value: unknown): void {
 }
 
 function validateConfig(config: Record<string, unknown>): void {
+	if (config.defaultSubagentContext !== undefined && config.defaultSubagentContext !== "fresh" && config.defaultSubagentContext !== "fork") {
+		throw new Error('config.defaultSubagentContext must be "fresh" or "fork"');
+	}
+	if (config.foregroundDetachShortcut !== undefined
+		&& (typeof config.foregroundDetachShortcut !== "string" || !isValidKeyId(config.foregroundDetachShortcut))) {
+		throw new Error("config.foregroundDetachShortcut must be a valid keybinding string such as \"ctrl+b\"");
+	}
 	if (config.artifactDir !== undefined && !ARTIFACT_DIR_PREFERENCES.has(config.artifactDir as ArtifactDirPreference)) {
 		throw new Error(`config.artifactDir must be "project", "session", or "temp"`);
 	}
-	if (config.legacyChainControls !== undefined && typeof config.legacyChainControls !== "boolean") {
-		throw new Error("config.legacyChainControls must be a boolean");
-	}
 	if (config.maxActiveAsyncRunsPerSession !== undefined
 		&& (typeof config.maxActiveAsyncRunsPerSession !== "number"
 			|| !Number.isInteger(config.maxActiveAsyncRunsPerSession)
@@ -85,6 +117,7 @@ function validateConfig(config: Record<string, unknown>): void {
 	validateFleetKeybindingsConfig(config.fleetKeybindings);
 	validateArtifactConfig(config.artifactConfig);
 	validateMainWindowRendererConfig(config.mainWindowRenderer);
+	validateOrcaProgressTabsConfig(config.orcaProgressTabs);
 }
 
 export function getConfigPath(): string {

package/src/extension/doctor.ts

@@ -134,7 +134,7 @@ function formatSessionLines(input: DoctorReportInput): string[] {
 
 function formatDiscovery(input: DoctorReportInput, deps: DoctorDeps): string[] {
 	return [
-		lineFromCheck("agents/chains", () => {
+		lineFromCheck("agents", () => {
 			const discovered = deps.discoverAgentsAll(input.cwd);
 			const agentCounts = {
 				builtin: discovered.builtin.length,
@@ -142,13 +142,10 @@ function formatDiscovery(input: DoctorReportInput, deps: DoctorDeps): string[] {
 				user: discovered.user.length,
 				project: discovered.project.length,
 			};
-			const chainCounts = discovered.chains.reduce<Record<AgentSource, number>>((counts, chain) => {
-				counts[chain.source] += 1;
-				return counts;
-			}, { builtin: 0, package: 0, user: 0, project: 0 });
+			const diagnostics = discovered.agentDiagnostics ?? [];
 			return [
 				`- agents: total ${agentCounts.builtin + agentCounts.package + agentCounts.user + agentCounts.project} (${formatSourceCounts(agentCounts)})`,
-				`- chains: total ${discovered.chains.length} (${formatSourceCounts(chainCounts)})`,
+				...diagnostics.map((diagnostic) => `- invalid agent ${diagnostic.name ?? diagnostic.filePath} (${diagnostic.source}): ${diagnostic.error}`),
 			].join("\n");
 		}),
 		lineFromCheck("skills", () => {

package/src/extension/fanout-child.ts

@@ -171,13 +171,13 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		allowMutatingManagementActions: false,
 	});
 
-	const params = createSubagentParamsSchema(config);
+	const params = createSubagentParamsSchema();
 	const tool: ToolDefinition<typeof params, Details> = {
 		name: "subagent",
 		label: "Subagent",
 		description: [
 			"Delegate to subagents from child-safe fanout mode.",
-			`Allowed management/control actions: list, get, status, interrupt, resume, steer${config.legacyChainControls === true ? ", append-step" : ""}, doctor.`,
+			"Allowed management/control actions: list, get, status, interrupt, resume, steer, doctor.",
 			"Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget) are blocked in this mode.",
 		].join("\n"),
 		parameters: params,