@agimon-ai/po-core 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/src/systems/main/adapters/headlessSessionHost.mjs

@@ -1,35 +1,39 @@
-import { modelConfigDirectory, modelSettingsDirectory } from "../../../../runtimePiSettings.mjs";
-import { DOOM_AGENT_MODEL_ENTRY_TYPE } from "../../../schemas/agentModel.mjs";
-import { readDoomBackgroundWorkService } from "../../../schemas/backgroundWork.mjs";
+import { piAgentDirectory } from "../../../services/piSettings/core.mjs";
+import { PO_AGENT_MODEL_ENTRY_TYPE } from "../../../schemas/agentModel.mjs";
+import { PO_BACKGROUND_WORK_CHANGED_EVENT, PO_BACKGROUND_WORK_SERVICE, readPoBackgroundWorkService } from "../../../schemas/backgroundWork.mjs";
 import "../../../../backgroundWork.mjs";
-import { CHATGPT_AUTH_PROVIDER_ID, registerChatgptAuthProvider } from "../../../services/chatgptAuth/index.mjs";
-import { DOOM_CHILD_SESSION_HOOKS_SERVICE, DOOM_CHILD_SESSION_MCP_TOOL_SERVICE, DOOM_CHILD_SESSION_SERVICE } from "../../child/types/childSession.mjs";
-import { registerDoomSessionEnvironment } from "../../../../runtimeCordisHost.mjs";
+import { CHATGPT_AUTH_PROVIDER_ID } from "../../../services/chatgptAuth/index.mjs";
+import { PO_CHILD_SESSION_HOOKS_SERVICE, PO_CHILD_SESSION_HOOK_REGISTRY_SERVICE, PO_CHILD_SESSION_MCP_TOOL_SERVICE, PO_CHILD_SESSION_SERVICE } from "../../child/types/childSession.mjs";
+import { registerPoSessionEnvironment } from "../../../../runtimeCordisHost.mjs";
 import "../../../../cordisHost.mjs";
-import { DoomHeadlessPromptAdmissionError, DoomSessionSetupError, isDoomHeadlessToolModelVisible } from "../../../schemas/headless.mjs";
-import { createHistoryOwnership } from "../../../../historyOwnership.mjs";
-import { SessionMetadataDoc } from "../../../../sqliteSessionStorage.mjs";
+import { PoHeadlessPromptAdmissionError, isPoHeadlessToolModelVisible } from "../../../schemas/headless.mjs";
+import { SessionMetadataDoc } from "../../../services/durableSession/docs.mjs";
 import { validationDetails } from "../../../../runtimeProtocol.mjs";
-import { createPiExtensionHost, formatSkillsForSystemPrompt, preloadPiExtensions, resolvePiSettingsPackageEntries } from "../../../services/piExtensionHost/index.mjs";
+import { formatSkillsForSystemPrompt } from "../../../services/skillPrompt/index.mjs";
 import { HeadlessHost, describeLoadSkillTool, headlessHarnessSkill } from "./headlessHost.mjs";
+import { abandonSubagent } from "../../../services/durableSubagents/index.mjs";
 import { createDirectHarnessRuntime } from "../../../server/directHarnessRuntime.mjs";
 import { harnessErrorMessage } from "../../../server/harnessErrorMessage.mjs";
 import { createChatgptImageClient } from "../../../services/chatgptImages/index.mjs";
 import { createChatgptWebSearchClient } from "../../../services/chatgptWebSearch/index.mjs";
 import { buildContextDetail } from "../../../../contextDetail.mjs";
-import { writeContextDetail } from "../../../../contextDetailStore.mjs";
-import { DOOM_CONTEXT_ENTRY_TYPE, projectContext } from "../../../../contextProjection.mjs";
+import { removeContextDetail, writeContextDetail } from "../../../../contextDetailStore.mjs";
+import { PO_CONTEXT_ENTRY_TYPE, projectContext } from "../../../../contextProjection.mjs";
 import { createHeadlessClient } from "../../../services/headlessClient/index.mjs";
+import { createNodeModelDependencies } from "../../../services/nodeModelDependencies/index.mjs";
+import { validateDirectHeadlessArgs } from "../../../services/piArgs/index.mjs";
+import { summarize } from "../../../services/piSummary/index.mjs";
 import { observe } from "../../../../serverTelemetry.mjs";
+import { PO_SESSION_TEMP_DIR, prepareSessionEnvironment } from "../../../services/sessionFiles/index.mjs";
 import { formatToolPrompt } from "../../../services/toolPrompt/index.mjs";
-import { createHeadlessChildSessionServiceProvider } from "../../child/adapters/headlessChildSessionService.mjs";
+import { composeChildSessionHooks, createHeadlessChildSessionServiceProvider, createPoChildSessionHookRegistry } from "../../child/adapters/headlessChildSessionService.mjs";
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
 import path from "node:path";
-import { DEFAULT_COMPACTION_SETTINGS, ModelRuntime, SettingsManager, generateSummary, getAgentDir, loadProjectContextFiles, parseArgs, resolveCliModel, resolveModelScopeWithDiagnostics } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
 import { BACKGROUND_CONTEXT, withAbortSignal } from "@earendil-works/chord/context";
-import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createAssistantMessageEventStream, isContextOverflow } from "@earendil-works/pi-ai";
+import { clampMaxTokensToContext } from "@earendil-works/pi-ai/api/simple-options";
 //#region src/systems/main/adapters/headlessSessionHost.ts
 const EXTERNAL_OPERATION = "external";
 const REMOTE_TOOL_WAIT_MS = 3e4;
@@ -46,7 +50,7 @@ function restoreHeadlessSelection(entries, fallback) {
 	for (let index = entries.length - 1; index >= 0 && projected === void 0; index -= 1) {
 		const entry = entries[index];
 		if (!isRecord(entry) || entry.type !== "custom" || !isRecord(entry.data)) continue;
-		if (projected === void 0 && entry.customType === "doom-context") {
+		if (projected === void 0 && entry.customType === "po-context") {
 			const selection = entry.data.selection;
 			if (!isRecord(selection) || typeof selection.majorMode !== "string") continue;
 			const domains = stringArray(selection.domains);
@@ -137,51 +141,6 @@ function isAgentMessage(value) {
 function isCompactResult(value) {
 	return isRecord(value) && typeof value.summary === "string" && typeof value.tokensBefore === "number" && Number.isFinite(value.tokensBefore) && Array.isArray(value.retainedTail) && value.retainedTail.every(isAgentMessage) && (value.usage === void 0 || isUsage(value.usage)) && (value.details === void 0 || isJsonValue(value.details));
 }
-const unsupported = (parsed) => {
-	const match = [
-		["--help", parsed.help],
-		["--version", parsed.version],
-		["--mode", parsed.mode],
-		["--print", parsed.print],
-		["--export", parsed.export],
-		["--no-session", parsed.noSession],
-		["--continue", parsed.continue],
-		["--resume", parsed.resume],
-		["--fork", parsed.fork],
-		["--list-models", parsed.listModels],
-		["--offline", parsed.offline],
-		["--tui-mode", parsed.tuiMode],
-		["--extensions", parsed.extensions],
-		["--no-extensions", parsed.noExtensions],
-		["--skills", parsed.skills],
-		["--no-skills", parsed.noSkills],
-		["--prompt-templates", parsed.promptTemplates],
-		["--no-prompt-templates", parsed.noPromptTemplates],
-		["--themes", parsed.themes],
-		["--no-themes", parsed.noThemes],
-		["--no-context-files", parsed.noContextFiles],
-		["--tools", parsed.tools],
-		["--exclude-tools", parsed.excludeTools],
-		["--no-tools", parsed.noTools],
-		["--no-builtin-tools", parsed.noBuiltinTools],
-		["--project-trust-override", parsed.projectTrustOverride],
-		["--verbose", parsed.verbose]
-	].find(([, value]) => value !== void 0 && value !== false);
-	if (match) return `Direct headless mode does not support ${match[0]}.`;
-	if (parsed.messages.length > 0 || parsed.fileArgs.length > 0) return "Direct headless mode does not support positional prompts or files.";
-	const unknown = parsed.unknownFlags.keys().next().value;
-	return typeof unknown === "string" ? `Direct headless mode does not support --${unknown}.` : void 0;
-};
-/** Validate the Pi flags that remain after Doom's harness flags are removed. */
-function validateDirectHeadlessArgs(agentArgs) {
-	if (agentArgs.includes("--mode")) throw new Error("Direct headless mode does not support --mode.");
-	const parsed = parseArgs([...agentArgs]);
-	const diagnostics = parsed.diagnostics.filter((diagnostic) => diagnostic.type === "error");
-	if (diagnostics.length) throw new Error(diagnostics.map((diagnostic) => diagnostic.message).join("\n"));
-	const error = unsupported(parsed);
-	if (error) throw new Error(error);
-	return parsed;
-}
 function modelIdentity(model) {
 	return {
 		provider: model.provider,
@@ -230,30 +189,6 @@ function modelMetadata(model) {
 		compat: Object.freeze(compat)
 	});
 }
-async function resolveModel(parsed, modelRuntime, settings) {
-	const cli = resolveCliModel({
-		cliProvider: parsed.provider,
-		cliModel: parsed.model,
-		cliThinking: parsed.thinking,
-		modelRuntime
-	});
-	if (cli.error) throw new Error(cli.error);
-	let scoped;
-	if (parsed.models !== void 0 && parsed.models.length > 0) {
-		scoped = (await resolveModelScopeWithDiagnostics(parsed.models, modelRuntime)).scopedModels[0]?.model;
-		if (scoped === void 0) throw new DoomSessionSetupError(`No configured model matched --models ${parsed.models.join(", ")}.`);
-	}
-	const configured = cli.model ?? scoped ?? (settings.getDefaultProvider() && settings.getDefaultModel() ? modelRuntime.getModel(settings.getDefaultProvider(), settings.getDefaultModel()) : void 0) ?? (await modelRuntime.getAvailable())[0];
-	if (configured === void 0) {
-		const agentDir = getAgentDir();
-		const runtimeError = modelRuntime.getError();
-		throw new DoomSessionSetupError(`No model is configured, so the session cannot start. Add a provider and its credentials in ${agentDir} (auth.json, or models.json for a custom provider), then set defaultProvider and defaultModel in ${path.join(agentDir, "settings.json")}.` + (runtimeError ? `\n\n${runtimeError}` : ""));
-	}
-	return {
-		model: configured,
-		thinkingLevel: cli.thinkingLevel ?? parsed.thinking ?? settings.getModelThinkingLevel(configured.provider, configured.id) ?? settings.getDefaultThinkingLevel()
-	};
-}
 function mapResources(resources) {
 	const skills = [];
 	const advertised = [];
@@ -309,9 +244,9 @@ function eventHook(event) {
 		message_start: "message_start",
 		message_update: "message_update",
 		message_end: "message_end",
-		tool_start: "tool_execution_start",
-		tool_update: "tool_execution_update",
-		tool_end: "tool_execution_end",
+		tool_execution_start: "tool_execution_start",
+		tool_execution_update: "tool_execution_update",
+		tool_execution_end: "tool_execution_end",
 		compaction_end: "session_compact",
 		navigation_start: "session_tree",
 		navigation_end: "session_tree"
@@ -323,13 +258,15 @@ function emitTo(listeners, frame) {
 		listener(frame);
 	} catch {}
 }
-function createHeadlessCompositionPublisher(runtime, host, environment, groups, readSystemPrompt) {
+function createHeadlessCompositionPublisher(runtime, host, environment, groups, readSystemPrompt, alive) {
 	let countTokens;
 	let contextRevision = 0;
 	let publishedContext;
 	let tail = Promise.resolve();
 	const publish = async (selection) => {
+		if (!alive()) return;
 		countTokens ??= (await import("gpt-tokenizer")).countTokens;
+		if (!alive()) return;
 		const inventory = host.getContextInventory(selection, countTokens);
 		const prompt = readSystemPrompt();
 		const promptCost = prompt === void 0 ? void 0 : {
@@ -365,11 +302,15 @@ function createHeadlessCompositionPublisher(runtime, host, environment, groups,
 				stage: prompt.stage
 			} }
 		});
-		await runtime.appendCustomEntry(DOOM_CONTEXT_ENTRY_TYPE, {
+		await runtime.appendCustomEntry(PO_CONTEXT_ENTRY_TYPE, {
+			...context,
+			revision
+		});
+		if (!alive()) return;
+		writeContextDetail(runtime.sessionId, revision, details, environment, {
 			...context,
 			revision
 		});
-		writeContextDetail(runtime.sessionId, revision, details, environment);
 		contextRevision = revision;
 		publishedContext = contextKey;
 	};
@@ -378,6 +319,41 @@ function createHeadlessCompositionPublisher(runtime, host, environment, groups,
 		return tail;
 	};
 }
+/**
+* The project instructions an MCP client may read: repository-relative, never the global AGENTS.md,
+* and never a file whose canonical path leaves the repository. Resolved once, like the files
+* themselves; an unresolvable root or agent directory is kept and reported on read.
+*/
+async function repositoryInstructions(platform, repoRoot, agentDir, files) {
+	const env = platform.env(repoRoot);
+	const canonical = async (target) => {
+		const result = await env.canonicalPath(target, BACKGROUND_CONTEXT);
+		if (!result.ok) throw result.error;
+		return result.value;
+	};
+	try {
+		const root = await canonical(repoRoot);
+		const globalInstruction = path.join(await canonical(agentDir), "AGENTS.md");
+		const out = [];
+		for (const { path: filePath, content } of files) {
+			const relative = path.relative(repoRoot, filePath);
+			if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) continue;
+			const canonicalPath = await canonical(filePath).catch(() => void 0);
+			if (canonicalPath === void 0 || canonicalPath === globalInstruction) continue;
+			const canonicalRelative = path.relative(root, canonicalPath);
+			if (canonicalRelative === "" || canonicalRelative.startsWith("..") || path.isAbsolute(canonicalRelative)) continue;
+			out.push({
+				path: relative.replaceAll(path.sep, "/"),
+				content
+			});
+		}
+		return out;
+	} catch (error) {
+		return error instanceof Error ? error : new Error(String(error));
+	} finally {
+		await env.cleanup(BACKGROUND_CONTEXT);
+	}
+}
 /** Create the gated, same-process host used by direct-headless startup tests. */
 /**
 * Composes one server session's host.
@@ -386,45 +362,26 @@ function createHeadlessCompositionPublisher(runtime, host, environment, groups,
 * registered under its id for them to read instead of `process.env`, and released with it.
 */
 async function createHeadlessSessionHost(options) {
-	const releaseEnvironment = registerDoomSessionEnvironment(options.sessionId, options.environment);
+	let releaseEnvironment;
 	try {
+		options = {
+			...options,
+			environment: await prepareSessionEnvironment(options)
+		};
+		releaseEnvironment = registerPoSessionEnvironment(options.sessionId, options.environment);
 		return await composeHeadlessSessionHost(options, releaseEnvironment);
 	} catch (error) {
-		releaseEnvironment();
+		removeContextDetail(options.sessionId, options.environment);
+		releaseEnvironment?.();
 		throw error;
 	}
 }
 async function composeHeadlessSessionHost(options, releaseEnvironment) {
 	const parsed = validateDirectHeadlessArgs(options.agentArgs);
-	const agentDir = getAgentDir();
-	const settings = SettingsManager.create(options.cwd, agentDir);
-	const modelDir = modelConfigDirectory(agentDir);
-	const settingsDir = modelSettingsDirectory(agentDir);
-	const modelSettings = settingsDir === agentDir ? settings : SettingsManager.create(options.cwd, settingsDir);
-	const modelRuntime = await ModelRuntime.create({
-		authPath: path.join(modelDir, "auth.json"),
-		modelsPath: path.join(modelDir, "models.json"),
-		refreshOnCreate: false
-	});
-	registerChatgptAuthProvider(modelRuntime);
-	const piExtensionPaths = options.piExtensions === false ? [] : [
-		...options.piExtensionFactories !== void 0 ? [] : options.piExtensionPaths ?? [],
-		...await resolvePiSettingsPackageEntries({
-			cwd: options.cwd,
-			agentDir,
-			settings,
-			...options.onNotice === void 0 ? {} : { onNotice: options.onNotice }
-		}),
-		...modelDir !== agentDir && fs.existsSync(path.join(modelDir, "extensions")) ? [path.join(modelDir, "extensions")] : []
-	];
-	const piPreload = await preloadPiExtensions({
-		cwd: options.cwd,
-		agentDir,
-		models: modelRuntime,
-		extensionPaths: [...new Set(piExtensionPaths)],
-		...options.piExtensions === false || options.piExtensionFactories === void 0 ? {} : { extensionFactories: await options.piExtensionFactories() },
-		...options.onNotice === void 0 ? {} : { onNotice: options.onNotice }
-	});
+	const models = await (options.modelDependencies ?? createNodeModelDependencies)(options);
+	const { agentDir, modelRuntime, projectContextFiles } = models;
+	const { platform } = options;
+	const instructions = await repositoryInstructions(platform, options.repoRoot, agentDir, projectContextFiles);
 	for (const override of options.providerOverrides?.() ?? []) {
 		if (!override.name.trim() || override.name !== override.name.trim()) throw new Error("Invalid native provider identity.");
 		const url = new URL(override.baseUrl);
@@ -432,7 +389,7 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 		if (modelRuntime.getRegisteredNativeProvider(override.name)) continue;
 		modelRuntime.registerProvider(override.name, { baseUrl: override.baseUrl });
 	}
-	const resolved = await resolveModel(parsed, modelRuntime, modelSettings);
+	const resolved = await models.resolveModel(parsed);
 	if (parsed.apiKey !== void 0) await modelRuntime.setRuntimeApiKey(resolved.model.provider, parsed.apiKey);
 	const reportedToolErrors = /* @__PURE__ */ new Set();
 	let promptPreparationFailed = false;
@@ -459,10 +416,6 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 	* Resolved once: cwd is fixed for the host's lifetime, and composeSystemPrompt runs
 	* on every generation.
 	*/
-	const projectContextFiles = loadProjectContextFiles({
-		cwd: options.cwd,
-		agentDir
-	});
 	const projectContextBlock = (() => {
 		if (projectContextFiles.length === 0) return "";
 		return `<project_context>\n\nProject-specific instructions and guidelines:\n\n${projectContextFiles.map(({ path: filePath, content }) => `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n`).join("\n")}\n</project_context>`;
@@ -484,7 +437,8 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			formatToolPrompt(toolGuidance),
 			skills,
 			...mapped.context,
-			workingDirectoryLine
+			workingDirectoryLine,
+			options.environment["PO_SESSION_TEMP_DIR"] ? `Session temporary folder: ${options.environment[PO_SESSION_TEMP_DIR]}\nUse this folder for generated scratch files outside the workspace. Keep workspace edits in place and save important deliverables in session artifacts. Temporary files may be removed by the operating system.` : ""
 		].filter(Boolean).join("\n\n");
 	};
 	/** The last prompt a turn actually built, once one has. */
@@ -576,17 +530,16 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			...terminate === void 0 ? {} : { terminate }
 		};
 	};
+	const selectionCommand = new AsyncLocalStorage();
 	const runtime = await createDirectHarnessRuntime({
 		cwd: options.cwd,
 		sessionId: options.sessionId,
 		...options.initialFastMode === void 0 ? {} : { initialFastMode: options.initialFastMode },
 		...options.initialAgentLocked === void 0 ? {} : { initialAgentLocked: options.initialAgentLocked },
 		...options.parentSessionId === void 0 ? {} : { parentSessionId: options.parentSessionId },
-		storage: "sqlite",
-		historyOwnership: createHistoryOwnership({ sourceFormat: "sqlite" }),
+		...options.resume ? { resume: true } : {},
+		platform,
 		sessionName: parsed.name ?? options.sessionName,
-		...parsed.session === void 0 ? {} : { sessionPath: parsed.session },
-		sessionsRoot: parsed.sessionDir ?? path.join(agentDir, "server", "sessions"),
 		models: modelRuntime,
 		model: resolved.model,
 		...resolved.thinkingLevel === void 0 ? {} : { thinkingLevel: resolved.thinkingLevel },
@@ -705,7 +658,12 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 				headlessHost.assertActive();
 				return false;
 			}
-			await headlessHost.dispatchCommand(name, args);
+			await selectionCommand.run([
+				"mode",
+				"domains",
+				"profile",
+				"minor"
+			].includes(name), () => headlessHost.dispatchCommand(name, args));
 			return true;
 		},
 		guardModelRequest: () => {
@@ -723,13 +681,17 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 				workspaceId: options.workspaceId,
 				groupingRoot: options.groupingRoot ?? options.repoRoot,
 				parentSessionId: options.parentSessionId,
-				sessionProvenance: options.sessionProvenance
+				sessionProvenance: options.sessionProvenance,
+				files: {
+					agentDirectory: path.resolve(piAgentDirectory(options.environment, options.platform.homeDirectory)),
+					...options.environment["PO_SESSION_TEMP_DIR"] === void 0 ? {} : { temporaryDirectory: options.environment[PO_SESSION_TEMP_DIR] }
+				}
 			});
 		}, BACKGROUND_CONTEXT);
 		const agent = await runtime.lane.agent(BACKGROUND_CONTEXT);
 		return {
 			model: agent.model ? modelRuntime.getModel(agent.model.provider, agent.model.modelId) : void 0,
-			entries: (await runtime.readEntries()).entries.filter((entry) => entry.type === "custom" && entry.customType === "doom-context").slice(-1)
+			entries: (await runtime.readEntries()).entries.filter((entry) => entry.type === "custom" && entry.customType === "po-context").slice(-1)
 		};
 	})().catch(async (error) => {
 		await runtime.dispose().catch((disposeError) => options.onNotice?.(`Session runtime failed to close: ${String(disposeError)}`));
@@ -749,6 +711,9 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 	const entries = opened.entries;
 	const listeners = /* @__PURE__ */ new Set();
 	const selectionListeners = /* @__PURE__ */ new Set();
+	const backgroundWorkListeners = /* @__PURE__ */ new Set();
+	let backgroundWorkActive = null;
+	let backgroundWorkBinding;
 	let latestSelection = options.selection;
 	const initialSelection = restoreHeadlessSelection(entries, options.selection);
 	let headlessHost;
@@ -768,24 +733,7 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 		if (!host || disposed) throw new Error("Session context is unavailable.");
 		const status = host.status;
 		if (!status.ready || status.requestedRevision !== status.appliedRevision) throw new Error("Session context is unavailable.");
-		const root = fs.realpathSync(options.repoRoot);
-		const globalInstruction = path.join(fs.realpathSync(agentDir), "AGENTS.md");
-		const instructions = projectContextFiles.flatMap(({ path: filePath, content }) => {
-			const relative = path.relative(options.repoRoot, filePath);
-			if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) return [];
-			try {
-				const canonicalPath = fs.realpathSync(filePath);
-				if (canonicalPath === globalInstruction) return [];
-				const canonicalRelative = path.relative(root, canonicalPath);
-				if (canonicalRelative === "" || canonicalRelative.startsWith("..") || path.isAbsolute(canonicalRelative)) return [];
-			} catch {
-				return [];
-			}
-			return [{
-				path: relative.replaceAll(path.sep, "/"),
-				content
-			}];
-		});
+		if (instructions instanceof Error) throw instructions;
 		const selection = host.context.selection;
 		const persona = host.appliedResources.find(({ name, kind }) => name === "po/profile-config" && kind === "context")?.text;
 		signal.throwIfAborted();
@@ -811,29 +759,22 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			persona: persona ?? null
 		};
 	};
+	const childHookRegistry = createPoChildSessionHookRegistry();
 	const childSessionProvider = createHeadlessChildSessionServiceProvider({
-		parentSessionId: runtime.sessionId,
+		runtime,
 		cwd: options.cwd,
-		sessionsRoot: parsed.sessionDir ?? path.join(agentDir, "server", "sessions"),
-		models: modelRuntime,
-		defaultModel: () => currentModel,
-		parentFastMode: async () => {
-			const state = await runtime.readState();
-			if (typeof state.fastMode !== "boolean") throw new Error("Parent Fast mode must be a boolean.");
-			return state.fastMode;
-		},
 		subscribeMcpTool: (listener) => {
 			return mcpServiceRoot?.on("internal/service", (name) => {
-				if (name === "doom/child-session-mcp-tool") listener();
+				if (name === "po/child-session-mcp-tool") listener();
 			}) ?? (() => void 0);
 		},
 		hooks: () => {
 			if (disposed || !headlessReady || !headlessHost?.status.ready) throw new Error("Headless capabilities are not installed.");
-			return mcpServiceRoot?.get(DOOM_CHILD_SESSION_HOOKS_SERVICE);
+			return composeChildSessionHooks([mcpServiceRoot?.get(PO_CHILD_SESSION_HOOKS_SERVICE), ...childHookRegistry.list()], options.onNotice);
 		},
 		mcpTool: () => {
 			if (disposed || !headlessReady || !headlessHost?.status.ready) return void 0;
-			return mcpServiceRoot?.get(DOOM_CHILD_SESSION_MCP_TOOL_SERVICE);
+			return mcpServiceRoot?.get(PO_CHILD_SESSION_MCP_TOOL_SERVICE);
 		}
 	});
 	const completeAuxiliaryModel = async (reference, request) => {
@@ -887,9 +828,9 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			const model = modelRuntime.getModel(provider, id);
 			return model ? modelMetadata(model) : void 0;
 		},
-		getAvailableModels() {
+		async getAvailableModels() {
 			if (disposed) throw new Error("The session is closed.");
-			return modelRuntime.getAvailableSnapshot().filter((model) => modelRuntime.hasConfiguredAuth(model.provider)).map(({ provider, id }) => ({
+			return (await modelRuntime.getAvailable()).filter((model) => modelRuntime.hasConfiguredAuth(model.provider)).map(({ provider, id }) => ({
 				provider,
 				id
 			}));
@@ -948,24 +889,27 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 					"max"
 				].includes(request.thinkingLevel)) throw new TypeError("Unsupported summary thinking level.");
 				let summaryFailure;
-				const summary = await generateSummary(messages, model, DEFAULT_COMPACTION_SETTINGS.reserveTokens, void 0, void 0, request.signal, request.instructions, request.previousSummary, request.thinkingLevel, (_model, context, options) => {
+				let overflowed = false;
+				const attempt = (target) => summarize(messages, target, request.signal, request.instructions, request.previousSummary, request.thinkingLevel, (_model, context, options) => {
 					const stream = createAssistantMessageEventStream();
-					runtime.completeModel(model, context, {
+					const maxTokens = target.maxTokens > 0 ? clampMaxTokensToContext(target, context, target.maxTokens) : options?.maxTokens;
+					runtime.completeModel(target, context, {
 						signal: options?.signal,
-						maxTokens: options?.maxTokens,
+						maxTokens,
 						cacheRetention: "none",
-						reasoningEffort: !model.reasoning || request.thinkingLevel === "off" ? "none" : request.thinkingLevel,
+						reasoningEffort: !target.reasoning || request.thinkingLevel === "off" ? "none" : request.thinkingLevel,
 						maxRetries: 0
 					}).then((response) => {
 						if (response.stopReason === "aborted") summaryFailure = new Error(response.errorMessage ?? "Summary was aborted.");
+						overflowed = isContextOverflow(response, target.contextWindow) || response.stopReason === "length" && maxTokens !== void 0 && maxTokens < target.maxTokens;
 						stream.end(response);
 					}, (error) => {
 						summaryFailure = error instanceof Error ? error : new Error(String(error));
 						stream.end({
 							role: "assistant",
-							api: model.api,
-							provider: model.provider,
-							model: model.id,
+							api: target.api,
+							provider: target.provider,
+							model: target.id,
 							content: [],
 							stopReason: request.signal?.aborted ? "aborted" : "error",
 							errorMessage: error instanceof Error ? error.message : String(error),
@@ -988,6 +932,15 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 					});
 					return stream;
 				});
+				let summary;
+				try {
+					summary = await attempt(model);
+				} catch (error) {
+					const widest = overflowed && !request.signal?.aborted ? (await modelRuntime.getAvailable()).reduce((best, item) => item.contextWindow > best.contextWindow ? item : best, model) : model;
+					if (widest === model) throw error;
+					summaryFailure = void 0;
+					summary = await attempt(widest);
+				}
 				request.signal?.throwIfAborted();
 				if (summaryFailure) throw summaryFailure;
 				if (!summary.trim()) throw new Error("Summarization returned an empty checkpoint.");
@@ -1024,13 +977,9 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 				if (settings.thinkingLevel !== void 0) await runtime.setThinkingLevel(settings.thinkingLevel);
 			},
 			async forkSource() {
-				const sessionFile = runtime.sessionFile;
-				if (typeof sessionFile !== "string") throw new Error("The parent session has no persisted journal.");
 				const { leafId } = await runtime.readEntries();
 				return {
-					kind: "v4-fork",
-					sessionFile,
-					branch: runtime.laneName,
+					kind: "fork",
 					...leafId === null ? {} : { entryId: leafId }
 				};
 			},
@@ -1047,12 +996,14 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 					if (disposed || !headlessReady || promptPreparationFailed || !headlessHost?.status.ready) throw new Error("Headless capability preparation is not ready.");
 					if (delivery !== "steer" && delivery !== "followUp") throw new TypeError("Custom message delivery must be steer or followUp.");
 					if (requestId !== void 0 && (typeof requestId !== "string" || !requestId.trim())) throw new TypeError("Custom message requestId must be a non-empty string.");
-					(await runtime.submitInternalMessage(informationalMessage(message), delivery, requestId)).settled.catch((error) => client.client.notify({
+					const submission = await runtime.submitInternalMessage(informationalMessage(message), delivery, requestId);
+					submission.settled.catch((error) => client.client.notify({
 						body: error instanceof Error ? error.message : String(error),
 						level: "error"
 					}));
+					if ("admitted" in submission) await submission.admitted;
 				} catch (error) {
-					throw new DoomHeadlessPromptAdmissionError(error);
+					throw new PoHeadlessPromptAdmissionError(error);
 				}
 			},
 			registerCheckpointBoundary(callback) {
@@ -1095,12 +1046,14 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			async admitPrompt(text, delivery, origin, requestId) {
 				try {
 					if (origin === "operator" && delivery === "followUp") return await runtime.followUp(text);
-					(delivery === "interrupt" ? await runtime.submitUserPrompt(text) : origin === "operator" ? await runtime.submitPrompt(text, void 0, delivery === "steer" ? "steer" : void 0) : await runtime.submitInternalMessage(text, delivery === "steer" ? "steer" : "followUp", requestId)).settled.catch((error) => client.client.notify({
+					const submission = delivery === "interrupt" ? await runtime.submitUserPrompt(text) : origin === "operator" ? await runtime.submitPrompt(text, void 0, delivery === "steer" ? "steer" : void 0) : await runtime.submitInternalMessage(text, delivery === "steer" ? "steer" : "followUp", requestId);
+					submission.settled.catch((error) => client.client.notify({
 						body: error instanceof Error ? error.message : String(error),
 						level: "error"
 					}));
+					if ("admitted" in submission) await submission.admitted;
 				} catch (error) {
-					throw new DoomHeadlessPromptAdmissionError(error);
+					throw new PoHeadlessPromptAdmissionError(error);
 				}
 			},
 			abort: () => runtime.abort(),
@@ -1152,7 +1105,7 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 				const serialized = JSON.stringify(projection);
 				if (serialized !== publishedAgentModel) {
 					publishedAgentModel = serialized;
-					await runtime.appendCustomEntry(DOOM_AGENT_MODEL_ENTRY_TYPE, projection);
+					await runtime.appendCustomEntry(PO_AGENT_MODEL_ENTRY_TYPE, projection);
 				}
 			}
 		}
@@ -1162,7 +1115,7 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			status: "started"
 		} : event);
 	});
-	let appliedFacetTools = [];
+	let appliedPackageTools = [];
 	let appliedSessionTools = /* @__PURE__ */ new Map();
 	let appliedSkills = /* @__PURE__ */ new Map();
 	let surfaceRevision = 0;
@@ -1265,13 +1218,13 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 	};
 	const applyToolSurface = async (tools) => {
 		toolSurfaceReady = false;
-		const modelTools = tools.filter(isDoomHeadlessToolModelVisible);
-		const facetTools = modelTools.map((tool) => toolAdapter(tool.name === "load_skill" ? {
+		const modelTools = tools.filter(isPoHeadlessToolModelVisible);
+		const packageTools = modelTools.map((tool) => toolAdapter(tool.name === "load_skill" ? {
 			...tool,
 			description: describeLoadSkillTool(tool.description, headlessHost?.appliedResources ?? [])
 		} : tool, () => headlessHost.context, reportedToolErrors));
-		const facetNames = headlessHost?.declaredToolNames ?? new Set(facetTools.map((tool) => tool.name));
-		const piTools = (piHost?.tools ?? []).filter((tool) => !facetNames.has(tool.name) && headlessHost?.allowsTool(tool.name) !== false).map((tool) => ({
+		const packageNames = headlessHost?.declaredToolNames ?? new Set(packageTools.map((tool) => tool.name));
+		const piTools = (piHost?.tools ?? []).filter((tool) => !packageNames.has(tool.name) && headlessHost?.allowsTool(tool.name) !== false).map((tool) => ({
 			...tool,
 			async execute(...args) {
 				headlessHost.assertActive();
@@ -1285,7 +1238,7 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			...tool.promptSnippet === void 0 ? {} : { promptSnippet: tool.promptSnippet },
 			...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines }
 		}))];
-		await runtime.replaceTools([...piTools, ...facetTools]);
+		await runtime.replaceTools([...piTools, ...packageTools]);
 		const next = /* @__PURE__ */ new Map();
 		for (const tool of piTools) next.set(tool.name, {
 			descriptor: {
@@ -1318,11 +1271,11 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 	*
 	* Deferred because the tool surface arbiter calls `setActiveTools` synchronously from inside
 	* `register`, and coalesced because several extensions register their restrictions in the same
-	* tick. The facet set is unchanged, so this never re-enters the kernel.
+	* tick. The package set is unchanged, so this never re-enters the kernel.
 	*/
 	let toolLine = Promise.resolve();
 	const applyLatestTools = () => {
-		toolLine = toolLine.catch(() => void 0).then(() => applyToolSurface(appliedFacetTools));
+		toolLine = toolLine.catch(() => void 0).then(() => applyToolSurface(appliedPackageTools));
 		return toolLine;
 	};
 	const scheduleToolReapply = () => {
@@ -1334,21 +1287,43 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			applyLatestTools().catch((error) => options.onNotice?.(`Pi extension tool refresh failed: ${error instanceof Error ? error.message : String(error)}`));
 		});
 	};
+	const publishBackgroundWork = (active) => {
+		if (disposed || active === backgroundWorkActive) return;
+		backgroundWorkActive = active;
+		for (const listener of backgroundWorkListeners) listener(active);
+	};
 	let admittedToolSurface;
-	const prepareFacets = (root) => {
+	const preparePackages = (root) => {
 		mcpServiceRoot = root;
+		backgroundWorkBinding = root.inject([PO_BACKGROUND_WORK_SERVICE], (context) => {
+			const service = readPoBackgroundWorkService(context);
+			if (service === void 0) return void 0;
+			let active = true;
+			const refresh = () => {
+				if (disposed || !active) return;
+				try {
+					const snapshot = service.snapshot(options.sessionId);
+					publishBackgroundWork(snapshot.items.length > 0 ? true : snapshot.errors.length > 0 ? null : false);
+				} catch {
+					publishBackgroundWork(null);
+				}
+			};
+			const unsubscribe = context.on(PO_BACKGROUND_WORK_CHANGED_EVENT, refresh);
+			refresh();
+			return () => {
+				active = false;
+				unsubscribe();
+				publishBackgroundWork(null);
+			};
+		});
 		root.plugin((context) => {
-			context.provide(DOOM_CHILD_SESSION_SERVICE, childSessionProvider.get());
+			context.provide(PO_CHILD_SESSION_SERVICE, childSessionProvider.get());
+			context.provide(PO_CHILD_SESSION_HOOK_REGISTRY_SERVICE, childHookRegistry);
 			context.effect(() => () => childSessionProvider.close(), "headless child session service lifetime");
 		});
-		if (headlessHost !== void 0) throw new Error("Direct headless facets were prepared more than once.");
-		if (piPreload !== void 0) piHost = createPiExtensionHost({
-			cwd: options.cwd,
-			agentDir,
-			models: modelRuntime,
-			settings,
+		if (headlessHost !== void 0) throw new Error("Direct headless packages were prepared more than once.");
+		if (models.piExtensions !== void 0) piHost = models.piExtensions({
 			runtime,
-			preload: piPreload,
 			getModel: () => currentModel,
 			getThinkingLevel: () => resolved.thinkingLevel ?? "off",
 			client: () => client?.client,
@@ -1360,6 +1335,20 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			...options.onNotice === void 0 ? {} : { onNotice: options.onNotice }
 		});
 		headlessHost = new HeadlessHost(root, {
+			scheduleSelection: (change, apply) => {
+				if (!selectionCommand.getStore()) return apply(change);
+				const previous = headlessHost.context.selection.state?.["minor-mode"] ?? [];
+				return runtime.runAtToolBoundary(() => selectionCommand.run(false, () => {
+					if (change.axis !== "state" || change.key !== "minor-mode") return apply(change);
+					const removed = previous.filter((name) => !change.values.includes(name));
+					const added = change.values.filter((name) => !previous.includes(name));
+					const current = headlessHost.context.selection.state?.["minor-mode"] ?? [];
+					return apply({
+						...change,
+						values: [.../* @__PURE__ */ new Set([...current.filter((name) => !removed.includes(name)), ...added])]
+					});
+				}));
+			},
 			candidates: options.candidates,
 			toolSurface: () => admittedToolSurface,
 			selection: initialSelection,
@@ -1375,13 +1364,13 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			},
 			...options.allowedTools === void 0 ? {} : { allowedTools: () => options.allowedTools },
 			applyTools: async (tools) => {
-				appliedFacetTools = tools;
+				appliedPackageTools = tools;
 				await applyLatestTools();
 			},
 			applyResources: async (next) => {
 				const mapped = mapResources(next);
-				const facetNames = new Set((mapped.harness.skills ?? []).map((skill) => skill.name));
-				const piSkills = (piHost?.skills ?? []).filter((skill) => !facetNames.has(skill.name));
+				const packageNames = new Set((mapped.harness.skills ?? []).map((skill) => skill.name));
+				const piSkills = (piHost?.skills ?? []).filter((skill) => !packageNames.has(skill.name));
 				const mergedSkills = [...piSkills, ...mapped.harness.skills ?? []];
 				await runtime.replaceResources(piSkills.length === 0 ? mapped.harness : {
 					...mapped.harness,
@@ -1399,16 +1388,16 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 					}];
 				}));
 				surfaceRevision += 1;
-				if (appliedFacetTools.some((tool) => tool.name === "load_skill")) await applyLatestTools();
+				if (appliedPackageTools.some((tool) => tool.name === "load_skill")) await applyLatestTools();
 			},
 			onApplied: async (selection) => {
 				options.publishSelectionStatus?.((source, text) => client.client.setStatus(source, text), selection);
 				latestSelection = selection;
 				for (const listener of selectionListeners) listener(selection);
 			},
-			onError: (error) => options.onNotice?.(`Headless selection failed: ${harnessErrorMessage(error)}`)
+			onError: (error, source) => options.onNotice?.(`Headless ${source ?? "host"} failed: ${harnessErrorMessage(error)}`)
 		});
-		publishComposition = createHeadlessCompositionPublisher(runtime, headlessHost, options.environment, (selection) => options.contextGroups?.(root, selection) ?? [], readSystemPrompt);
+		publishComposition = createHeadlessCompositionPublisher(runtime, headlessHost, options.environment, (selection) => options.contextGroups?.(root, selection) ?? [], readSystemPrompt, () => !disposed);
 		headlessHost.subscribeSelection(async (selection) => {
 			if (!headlessReady || !headlessHost?.status.ready) return;
 			try {
@@ -1419,16 +1408,16 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			await publishComposition(selection);
 		});
 	};
-	const activateFacets = async (installed) => {
+	const activatePackages = async (installedPackages) => {
 		if (headlessHost === void 0) throw new Error("Direct headless host was not prepared.");
 		const host = headlessHost;
 		const assertLive = () => {
 			if (disposed) throw new Error("The session was closed while it was starting.");
 		};
 		requiredServerPackages = await options.requiredServerPackages?.() ?? [];
-		installedServerPackages = installed.installedPackages;
+		installedServerPackages = installedPackages;
 		assertLive();
-		host.setAvailableSources(installed.installedPackages);
+		host.setAvailableSources(installedPackages);
 		if (piHost !== void 0) try {
 			await piHost.load();
 		} catch (error) {
@@ -1445,6 +1434,22 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 		assertLive();
 		await host.dispatchHook("session_start", {});
 		await publishComposition();
+		const children = childSessionProvider.get();
+		for (const run of await children.stored?.() ?? []) {
+			if (run.settled) continue;
+			const runId = run.request.runId;
+			try {
+				await children.restore?.(runId);
+			} catch (error) {
+				options.onNotice?.(`Child run ${runId} could not resume: ${harnessErrorMessage(error)}`);
+				assertLive();
+				const conversationId = await abandonSubagent(runtime.harness, runId, BACKGROUND_CONTEXT).catch((abandonError) => {
+					options.onNotice?.(`Child run ${runId} could not be stopped: ${harnessErrorMessage(abandonError)}`);
+				});
+				if (conversationId !== void 0) runtime.closeLane(conversationId);
+			}
+		}
+		assertLive();
 		(await runtime.admitResume()).settled.catch((error) => options.onNotice?.(`Session resume failed: ${harnessErrorMessage(error)}`));
 		assertLive();
 	};
@@ -1458,6 +1463,13 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			mcpLifecycle.abort();
 			chatgptLifecycle.abort();
 			const failures = [];
+			removeContextDetail(runtime.sessionId, options.environment);
+			backgroundWorkListeners.clear();
+			try {
+				await backgroundWorkBinding?.dispose();
+			} catch (error) {
+				failures.push(error);
+			}
 			try {
 				await runtime.interrupt();
 			} catch (error) {
@@ -1468,6 +1480,11 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			} catch (error) {
 				failures.push(error);
 			}
+			try {
+				await childSessionProvider.close();
+			} catch (error) {
+				failures.push(error);
+			}
 			try {
 				await runtime.dispose();
 			} catch (error) {
@@ -1486,11 +1503,6 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 			client?.dispose();
 			unsubscribePresentation();
 			unsubscribeEvents();
-			try {
-				await childSessionProvider.close();
-			} catch (error) {
-				failures.push(error);
-			}
 			releaseEnvironment();
 			if (failures.length) throw new AggregateError(failures, "Headless session shutdown failed");
 		})();
@@ -1660,7 +1672,7 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 		runtime,
 		async readExecutionState() {
 			const state = await runtime.readState();
-			const backgroundWork = mcpServiceRoot === void 0 ? void 0 : readDoomBackgroundWorkService(mcpServiceRoot)?.snapshot(options.sessionId);
+			const backgroundWork = mcpServiceRoot === void 0 ? void 0 : readPoBackgroundWorkService(mcpServiceRoot)?.snapshot(options.sessionId);
 			return {
 				isIdle: state.isIdle === true,
 				hasPendingMessages: Number(state.pendingMessageCount) > 0,
@@ -1673,11 +1685,13 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 		},
 		toolSurface,
 		mcpSurface,
-		prepareFacets,
-		activateFacets,
+		preparePackages,
+		activatePackages,
 		canDispatch: () => !disposed && headlessReady && !promptPreparationFailed && headlessHost?.status.ready === true,
+		childThread: (runId) => childSessionProvider.get().thread(runId),
 		onPresentationFrame(listener) {
 			listeners.add(listener);
+			client?.replay(listener);
 			return () => listeners.delete(listener);
 		},
 		onSelection(listener) {
@@ -1687,6 +1701,12 @@ async function composeHeadlessSessionHost(options, releaseEnvironment) {
 				selectionListeners.delete(listener);
 			};
 		},
+		onBackgroundWork(listener) {
+			if (disposed) return () => void 0;
+			backgroundWorkListeners.add(listener);
+			listener(backgroundWorkActive);
+			return () => backgroundWorkListeners.delete(listener);
+		},
 		respondToExtensionUi(frame) {
 			return client?.receive(frame) ?? false;
 		},