@oh-my-pi/pi-coding-agent 15.12.4 → 15.13.0

package/src/extensibility/plugins/manager.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import {
 	getPluginsDir,
@@ -11,6 +12,8 @@ import {
 	logger,
 } from "@oh-my-pi/pi-utils";
 import { type GitSource, parseGitUrl } from "./git-url";
+import { installLegacyPiSpecifierShim, loadLegacyPiModule } from "./legacy-pi-compat";
+import { resolvePluginManifestEntries } from "./loader";
 import { extractPackageName, parsePluginSpec } from "./parser";
 import type {
 	DoctorCheck,
@@ -74,6 +77,34 @@ function gitInstallSpec(original: string, source: GitSource): string {
 	return `${source.repo}#${source.ref}`;
 }
 
+function findGitPackageName(source: GitSource, deps: Record<string, string>): string | undefined {
+	for (const [key, value] of Object.entries(deps)) {
+		if (typeof value !== "string") {
+			continue;
+		}
+		const installedSource = parseGitUrl(value);
+		if (installedSource && installedSource.host === source.host && installedSource.path === source.path) {
+			return key;
+		}
+	}
+	return undefined;
+}
+
+function hasDefaultExport(value: unknown): value is { default?: unknown } {
+	return typeof value === "object" && value !== null && "default" in value;
+}
+
+function hasExtensionFactoryExport(module: unknown): boolean {
+	return typeof module === "function" || (hasDefaultExport(module) && typeof module.default === "function");
+}
+
+interface PluginPackageSnapshot {
+	readonly actualName: string;
+	readonly packagePath: string;
+	readonly backupRoot: string;
+	readonly backupPath: string;
+}
+
 // =============================================================================
 // Plugin Manager
 // =============================================================================
@@ -173,6 +204,88 @@ export class PluginManager {
 		}
 	}
 
+	async #snapshotInstalledPackage(actualName: string | undefined): Promise<PluginPackageSnapshot | null> {
+		if (!actualName) {
+			return null;
+		}
+		const packagePath = path.join(getPluginsNodeModules(), actualName);
+		try {
+			await fs.promises.lstat(packagePath);
+		} catch (err) {
+			if (isEnoent(err)) {
+				return null;
+			}
+			throw err;
+		}
+
+		const backupRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "omp-plugin-backup-"));
+		const backupPath = path.join(backupRoot, "package");
+		await fs.promises.cp(packagePath, backupPath, { recursive: true, verbatimSymlinks: true });
+		return { actualName, packagePath, backupRoot, backupPath };
+	}
+
+	async #cleanupSnapshot(snapshot: PluginPackageSnapshot | null): Promise<void> {
+		if (!snapshot) {
+			return;
+		}
+		try {
+			await fs.promises.rm(snapshot.backupRoot, { recursive: true, force: true });
+		} catch (err) {
+			logger.warn("Failed to remove plugin install backup", { plugin: snapshot.actualName, error: String(err) });
+		}
+	}
+
+	async #rollbackFailedInstall(
+		actualName: string,
+		packageJsonBefore: string,
+		snapshot: PluginPackageSnapshot | null,
+	): Promise<void> {
+		await Bun.write(getPluginsPackageJson(), packageJsonBefore);
+		const packagePath = path.join(getPluginsNodeModules(), actualName);
+		await fs.promises.rm(packagePath, { recursive: true, force: true });
+		if (!snapshot) {
+			return;
+		}
+		await fs.promises.mkdir(path.dirname(snapshot.packagePath), { recursive: true });
+		await fs.promises.cp(snapshot.backupPath, snapshot.packagePath, { recursive: true, verbatimSymlinks: true });
+	}
+
+	async #validateInstalledExtensions(plugin: InstalledPlugin): Promise<void> {
+		const declaredEntries = resolvePluginManifestEntries(plugin, "extensions");
+		if (declaredEntries.length === 0) {
+			return;
+		}
+
+		const errors: string[] = [];
+		const loadable: string[] = [];
+		for (const { entry, resolvedPath } of declaredEntries) {
+			if (resolvedPath === null) {
+				errors.push(`${entry}: declared extension entry not found on disk`);
+			} else {
+				loadable.push(resolvedPath);
+			}
+		}
+
+		if (loadable.length > 0) {
+			installLegacyPiSpecifierShim();
+			for (const extensionPath of loadable) {
+				try {
+					const module = await loadLegacyPiModule(extensionPath);
+					if (!hasExtensionFactoryExport(module)) {
+						errors.push(`${extensionPath}: extension does not export a valid factory function`);
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					errors.push(`${extensionPath}: ${message}`);
+				}
+			}
+		}
+
+		if (errors.length > 0) {
+			throw new Error(`Plugin ${plugin.name} extension validation failed:\n${errors.join("\n")}`);
+		}
+	}
+
 	// ==========================================================================
 	// Install / Uninstall
 	// ==========================================================================
@@ -217,113 +330,131 @@ export class PluginManager {
 			};
 		}
 		const pkgJsonPath = getPluginsPackageJson();
-		const depsBefore = gitSource ? await this.#readDeps(pkgJsonPath) : {};
+		const packageJsonBefore = await Bun.file(pkgJsonPath).text();
+		const depsBefore = await this.#readDeps(pkgJsonPath);
 		const packageInstallSpec = gitSource ? gitInstallSpec(spec.packageName, gitSource) : spec.packageName;
+		const existingActualName = gitSource
+			? findGitPackageName(gitSource, depsBefore)
+			: extractPackageName(spec.packageName);
+		const packageSnapshot = await this.#snapshotInstalledPackage(existingActualName);
 
-		// Run npm install
-		const proc = Bun.spawn(["bun", "install", packageInstallSpec], {
-			cwd: getPluginsDir(),
-			stdin: "ignore",
-			stdout: "pipe",
-			stderr: "pipe",
-			windowsHide: true,
-		});
+		try {
+			// Run npm install
+			const proc = Bun.spawn(["bun", "install", packageInstallSpec], {
+				cwd: getPluginsDir(),
+				stdin: "ignore",
+				stdout: "pipe",
+				stderr: "pipe",
+				windowsHide: true,
+			});
 
-		const exitCode = await proc.exited;
-		if (exitCode !== 0) {
-			const stderr = await new Response(proc.stderr).text();
-			throw new Error(`npm install failed: ${stderr}`);
-		}
-		// Resolve actual package name. npm specs encode the name (strip version);
-		// git specs do not, so diff plugins/package.json deps to find the new entry.
-		let actualName: string;
-		if (gitSource) {
-			const depsAfter = await this.#readDeps(pkgJsonPath);
-			let resolved: string | undefined;
-			for (const key of Object.keys(depsAfter)) {
-				if (!(key in depsBefore)) {
-					resolved = key;
-					break;
-				}
+			const exitCode = await proc.exited;
+			if (exitCode !== 0) {
+				const stderr = await new Response(proc.stderr).text();
+				throw new Error(`npm install failed: ${stderr}`);
 			}
-			// Fallback: a force-reinstall of an already-present git plugin will not
-			// add a new key, just rewrite the existing one to the new spec value.
-			// Match by the install value for force-reinstalls where no new key is
-			// added (non-GitHub shorthands are normalized before bun sees them).
-			if (!resolved) {
-				const needle = packageInstallSpec.replace(/^git\+/i, "");
-				for (const [key, value] of Object.entries(depsAfter)) {
-					if (typeof value === "string" && value.includes(needle)) {
+			// Resolve actual package name. npm specs encode the name (strip version);
+			// git specs do not, so diff plugins/package.json deps to find the new entry.
+			let actualName: string;
+			if (gitSource) {
+				const depsAfter = await this.#readDeps(pkgJsonPath);
+				let resolved: string | undefined;
+				for (const key of Object.keys(depsAfter)) {
+					if (!(key in depsBefore)) {
 						resolved = key;
 						break;
 					}
 				}
+				// Fallback: a force-reinstall of an already-present git plugin will not
+				// add a new key, just rewrite the existing one to the new spec value.
+				// Match by repository identity, not by ref, so failed upgrades from
+				// one ref to another still resolve to the original package name.
+				if (!resolved) {
+					resolved = findGitPackageName(gitSource, depsAfter);
+				}
+				if (!resolved) {
+					throw new Error(
+						`Installed ${spec.packageName} but could not determine package name from plugins/package.json`,
+					);
+				}
+				actualName = resolved;
+			} else {
+				actualName = extractPackageName(spec.packageName);
 			}
-			if (!resolved) {
-				throw new Error(
-					`Installed ${spec.packageName} but could not determine package name from plugins/package.json`,
-				);
-			}
-			actualName = resolved;
-		} else {
-			actualName = extractPackageName(spec.packageName);
-		}
-		const pkgPath = path.join(getPluginsNodeModules(), actualName, "package.json");
+			const pkgPath = path.join(getPluginsNodeModules(), actualName, "package.json");
 
-		let pkg: { name: string; version: string; omp?: PluginManifest; pi?: PluginManifest };
-		try {
-			pkg = await Bun.file(pkgPath).json();
-		} catch (err) {
-			if (isEnoent(err)) {
-				throw new Error(`Package installed but package.json not found at ${pkgPath}`);
+			let pkg: { name: string; version: string; omp?: PluginManifest; pi?: PluginManifest };
+			try {
+				pkg = await Bun.file(pkgPath).json();
+			} catch (err) {
+				if (isEnoent(err)) {
+					throw new Error(`Package installed but package.json not found at ${pkgPath}`);
+				}
+				throw err;
 			}
-			throw err;
-		}
-		const manifest: PluginManifest = pkg.omp || pkg.pi || { version: pkg.version };
-		manifest.version = pkg.version;
-
-		// Resolve enabled features
-		let enabledFeatures: string[] | null = null;
-		if (spec.features === "*") {
-			// All features
-			enabledFeatures = manifest.features ? Object.keys(manifest.features) : null;
-		} else if (Array.isArray(spec.features)) {
-			if (spec.features.length > 0) {
-				// Validate requested features exist
-				if (manifest.features) {
-					for (const feat of spec.features) {
-						if (!(feat in manifest.features)) {
-							throw new Error(
-								`Unknown feature "${feat}" in ${actualName}. Available: ${Object.keys(manifest.features).join(", ")}`,
-							);
+			const manifest: PluginManifest = pkg.omp || pkg.pi || { version: pkg.version };
+			manifest.version = pkg.version;
+
+			// Resolve enabled features
+			let enabledFeatures: string[] | null = null;
+			if (spec.features === "*") {
+				// All features
+				enabledFeatures = manifest.features ? Object.keys(manifest.features) : null;
+			} else if (Array.isArray(spec.features)) {
+				if (spec.features.length > 0) {
+					// Validate requested features exist
+					if (manifest.features) {
+						for (const feat of spec.features) {
+							if (!(feat in manifest.features)) {
+								throw new Error(
+									`Unknown feature "${feat}" in ${actualName}. Available: ${Object.keys(manifest.features).join(", ")}`,
+								);
+							}
 						}
 					}
+					enabledFeatures = spec.features;
+				} else {
+					// Empty array = no optional features
+					enabledFeatures = [];
 				}
-				enabledFeatures = spec.features;
-			} else {
-				// Empty array = no optional features
-				enabledFeatures = [];
 			}
-		}
-		// null = use defaults
+			// null = use defaults
 
-		// Update runtime config
-		const config = await this.#ensureConfigLoaded();
-		config.plugins[pkg.name] = {
-			version: pkg.version,
-			enabledFeatures,
-			enabled: true,
-		};
-		await this.#saveRuntimeConfig();
+			const installedPlugin: InstalledPlugin = {
+				name: pkg.name,
+				version: pkg.version,
+				path: path.join(getPluginsNodeModules(), actualName),
+				manifest,
+				enabledFeatures,
+				enabled: true,
+			};
 
-		return {
-			name: pkg.name,
-			version: pkg.version,
-			path: path.join(getPluginsNodeModules(), actualName),
-			manifest,
-			enabledFeatures,
-			enabled: true,
-		};
+			try {
+				await this.#validateInstalledExtensions(installedPlugin);
+			} catch (err) {
+				try {
+					await this.#rollbackFailedInstall(actualName, packageJsonBefore, packageSnapshot);
+				} catch (rollbackErr) {
+					const message = err instanceof Error ? err.message : String(err);
+					const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+					throw new Error(`${message}\nRollback failed: ${rollbackMessage}`);
+				}
+				throw err;
+			}
+
+			// Update runtime config
+			const config = await this.#ensureConfigLoaded();
+			config.plugins[pkg.name] = {
+				version: pkg.version,
+				enabledFeatures,
+				enabled: true,
+			};
+			await this.#saveRuntimeConfig();
+
+			return installedPlugin;
+		} finally {
+			await this.#cleanupSnapshot(packageSnapshot);
+		}
 	}
 
 	/**

package/src/extensibility/shared-events.ts

@@ -17,7 +17,7 @@ import type { CompactionPreparation, CompactionResult } from "@oh-my-pi/pi-agent
 import type { ImageContent, TextContent, ToolResultMessage } from "@oh-my-pi/pi-ai";
 import type { Rule } from "../capability/rule";
 import type { Goal, GoalModeState } from "../goals/state";
-import type { BranchSummaryEntry, CompactionEntry, SessionEntry } from "../session/session-manager";
+import type { BranchSummaryEntry, CompactionEntry, SessionEntry } from "../session/session-entries";
 import type { TodoItem } from "../tools/todo";
 
 // ============================================================================

package/src/extensibility/skills.ts

@@ -1,6 +1,11 @@
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import { getProjectDir } from "@oh-my-pi/pi-utils";
+import {
+	isValidManagedSkillName,
+	MANAGED_SKILLS_PROVIDER_ID,
+	sanitizeManagedDescription,
+} from "../autolearn/managed-skills";
 import { skillCapability } from "../capability/skill";
 import type { SourceMeta } from "../capability/types";
 import type { SkillsSettings } from "../config/settings";
@@ -54,6 +59,21 @@ export function resetActiveSkillsForTests(): void {
 	activeSkills = [];
 }
 
+/**
+ * Whether `name` is already claimed by an active authored (non-managed) skill.
+ *
+ * Managed (auto-learn) skills resolve dead-last in discovery, so an authored
+ * skill of the same name always wins (see `loadSkills`) and a managed skill
+ * written under an authored name is silently dropped — it never surfaces.
+ * `manage_skill` create consults this to refuse the write up front instead of
+ * reporting a false "Created" for a skill that can never appear.
+ */
+export function isNameClaimedByAuthoredSkill(name: string): boolean {
+	return getActiveSkills().some(
+		skill => skill.name === name && skill._source?.provider !== MANAGED_SKILLS_PROVIDER_ID,
+	);
+}
+
 export interface LoadSkillsFromDirOptions {
 	/** Directory to scan for skills */
 	dir: string;
@@ -119,24 +139,23 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	if (!enabled) {
 		return { skills: [], warnings: [] };
 	}
-
 	// Fall-through gate for third-party CLI providers (claude-plugins, opencode,
-	// gemini, github, ...) that share user intent with the named source toggles
-	// but don't have a dedicated control of their own. The OMP-native providers
-	// (`agents`, `native`) get explicit toggles above and never fall through:
-	// disabling Claude/Codex must not silently break `.agent[s]/skills`
-	// discovery (issue #2401).
-	const anyBuiltInSkillSourceEnabled =
-		enableCodexUser ||
-		enableClaudeUser ||
-		enableClaudeProject ||
-		enablePiUser ||
-		enablePiProject ||
-		enableAgentsUser ||
-		enableAgentsProject;
+	// gemini, github, ...) that share user intent with the named third-party
+	// source toggles but don't have a dedicated control of their own. Only the
+	// third-party toggles count here: the OMP-native providers (`agents`,
+	// `native`) get explicit branches in `isSourceEnabled` below, so folding
+	// them into the fallback would re-enable unrelated third-party CLIs whenever
+	// the user kept the default `.agent[s]/skills` toggles on while turning off
+	// Codex/Claude/Pi (issue #2401 / PR #2405 review).
+	const anyThirdPartySkillToggleEnabled =
+		enableCodexUser || enableClaudeUser || enableClaudeProject || enablePiUser || enablePiProject;
 
 	function isSourceEnabled(source: SourceMeta): boolean {
 		const { provider, level } = source;
+		// Managed skills (auto-learn) are OMP-native and discovered unconditionally
+		// — third-party CLI toggles must never silently hide them (cf. #2401). The
+		// master `enabled` flag above still gates them.
+		if (provider === MANAGED_SKILLS_PROVIDER_ID) return true;
 		if (provider === "codex" && level === "user") return enableCodexUser;
 		if (provider === "claude" && level === "user") return enableClaudeUser;
 		if (provider === "claude" && level === "project") return enableClaudeProject;
@@ -144,7 +163,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		if (provider === "native" && level === "project") return enablePiProject;
 		if (provider === "agents" && level === "user") return enableAgentsUser;
 		if (provider === "agents" && level === "project") return enableAgentsProject;
-		return anyBuiltInSkillSourceEnabled;
+		return anyThirdPartySkillToggleEnabled;
 	}
 
 	// Use capability API to load all skills
@@ -192,6 +211,9 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	// Process skills with resolved paths
 	for (let i = 0; i < filteredSkills.length; i++) {
 		const capSkill = filteredSkills[i];
+		// Managed (auto-learn) skills are resolved dead-last (below) so any
+		// authored skill of the same name — from ANY provider or custom dir — wins.
+		if (capSkill._source.provider === MANAGED_SKILLS_PROVIDER_ID) continue;
 		const resolvedPath = realPaths[i];
 
 		// Skip silently if we've already loaded this exact file (via symlink)
@@ -285,6 +307,65 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		}
 	}
 
+	// Managed (auto-learn) skills resolve dead-last with first-wins. Source from
+	// result.all (pre-dedup): capability-level dedup runs BEFORE isSourceEnabled,
+	// so a managed skill can be shadowed by a higher-priority authored skill that
+	// is itself disabled here — managed must stay visible regardless of toggles.
+	// Validate the on-disk name (a hand-placed managed file could carry an unsafe
+	// frontmatter name) and re-sanitize the description on read. Descriptions and
+	// names both render unescaped into the system prompt.
+	const managedCandidates = result.all.filter(
+		capSkill =>
+			capSkill._source.provider === MANAGED_SKILLS_PROVIDER_ID &&
+			isValidManagedSkillName(capSkill.name) &&
+			!disabledSkillNames.has(capSkill.name) &&
+			!matchesIgnorePatterns(capSkill.name) &&
+			matchesIncludePatterns(capSkill.name),
+	);
+	// Names claimed by any ENABLED authored skill (from the pre-dedup superset).
+	// Managed defers to these even when capability dedup hid an enabled authored
+	// skill behind a disabled higher-priority one, so managed never masks it.
+	const enabledAuthoredNames = new Set(
+		result.all
+			.filter(
+				capSkill => capSkill._source.provider !== MANAGED_SKILLS_PROVIDER_ID && isSourceEnabled(capSkill._source),
+			)
+			.map(capSkill => capSkill.name),
+	);
+	const managedRealPaths = await Promise.all(
+		managedCandidates.map(async capSkill => {
+			try {
+				return await fs.realpath(capSkill.path);
+			} catch {
+				return capSkill.path;
+			}
+		}),
+	);
+	for (let i = 0; i < managedCandidates.length; i++) {
+		const capSkill = managedCandidates[i];
+		const resolvedPath = managedRealPaths[i];
+		if (realPathSet.has(resolvedPath)) continue;
+		if (enabledAuthoredNames.has(capSkill.name)) continue; // an enabled authored skill owns this name
+		// Already claimed — e.g. by a custom-directory skill. LOAD-BEARING: custom
+		// dirs never enter `result.all`, so they are absent from `enabledAuthoredNames`
+		// above; this map check is the ONLY veto that lets a custom-dir authored skill
+		// win over a same-named managed one. The custom-dir loop (which populates
+		// skillMap, ~30 lines up) MUST run before this block — do not reorder.
+		if (skillMap.has(capSkill.name)) continue;
+		const rawDescription =
+			typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "";
+		skillMap.set(capSkill.name, {
+			name: capSkill.name,
+			description: sanitizeManagedDescription(rawDescription),
+			filePath: capSkill.path,
+			baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
+			source: `${capSkill._source.provider}:${capSkill.level}`,
+			hide: capSkill.frontmatter?.hide === true || capSkill.frontmatter?.disableModelInvocation === true,
+			_source: capSkill._source,
+		});
+		realPathSet.add(resolvedPath);
+	}
+
 	const skills = Array.from(skillMap.values());
 	// Deterministic ordering for prompt stability (case-insensitive, then exact name, then path).
 	skills.sort((a, b) => compareSkillOrder(a.name, a.filePath, b.name, b.filePath));

package/src/goals/guided-setup.ts

@@ -0,0 +1,133 @@
+import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent-core";
+import type { Tool } from "@oh-my-pi/pi-ai";
+import { prompt } from "@oh-my-pi/pi-utils";
+import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
+import guidedGoalInterviewPrompt from "../prompts/goals/guided-goal-interview.md" with { type: "text" };
+import guidedGoalSystemPrompt from "../prompts/goals/guided-goal-system.md" with { type: "text" };
+import type { AgentSession } from "../session/agent-session";
+import { toReasoningEffort } from "../thinking";
+
+const RESPOND_TOOL_NAME = "respond";
+
+const RESPOND_TOOL: Tool = {
+	name: RESPOND_TOOL_NAME,
+	description: "Return the next guided-goal interview step.",
+	parameters: {
+		type: "object",
+		properties: {
+			kind: { type: "string", enum: ["question", "ready"] },
+			question: { type: "string" },
+			objective: { type: "string" },
+		},
+		required: ["kind"],
+		additionalProperties: false,
+	},
+	strict: false,
+};
+
+export interface GuidedGoalMessage {
+	role: "user" | "assistant";
+	content: string;
+}
+
+export type GuidedGoalTurnResult =
+	| { kind: "question"; question: string; objective?: string }
+	| { kind: "ready"; objective: string };
+
+export interface GuidedGoalTurnOptions {
+	messages: readonly GuidedGoalMessage[];
+	signal?: AbortSignal;
+}
+
+function parseGuidedGoalPayload(value: unknown): GuidedGoalTurnResult {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("guided goal returned an invalid response");
+	}
+	const payload = value as Record<string, unknown>;
+	if (payload.kind === "question" && typeof payload.question === "string" && payload.question.trim()) {
+		const question = payload.question.trim();
+		if (typeof payload.objective === "string" && payload.objective.trim()) {
+			return { kind: "question", question, objective: payload.objective.trim() };
+		}
+		return { kind: "question", question };
+	}
+	if (payload.kind === "ready" && typeof payload.objective === "string" && payload.objective.trim()) {
+		return { kind: "ready", objective: payload.objective.trim() };
+	}
+	throw new Error("guided goal returned an invalid response");
+}
+
+function parseToolArguments(value: unknown): unknown {
+	return typeof value === "string" ? parseJsonPayload(value) : value;
+}
+
+export async function runGuidedGoalTurn(
+	session: AgentSession,
+	options: GuidedGoalTurnOptions,
+): Promise<GuidedGoalTurnResult> {
+	const plan = session.resolveRoleModelWithThinking("plan");
+	const resolved = plan.model ? plan : session.resolveRoleModelWithThinking("slow");
+	if (!resolved.model) {
+		throw new Error("No plan or slow model is available for /guided-goal.");
+	}
+
+	const apiKey = await session.modelRegistry.getApiKey(resolved.model, session.sessionId);
+	if (!apiKey) {
+		throw new Error(`No API key for ${resolved.model.provider}/${resolved.model.id}`);
+	}
+
+	const userPrompt = prompt.render(guidedGoalInterviewPrompt, {
+		messages: options.messages.map(message => ({ label: message.role.toUpperCase(), content: message.content })),
+	});
+	// Secret obfuscation: route the user-authored transcript through the session obfuscator the
+	// same way normal turns do, so an API key / secret typed into the rough goal or an answer is
+	// never sent verbatim to the plan/slow provider. Deobfuscated again below before display/use.
+	const obfuscator = session.obfuscator;
+	const promptText = obfuscator?.hasSecrets() ? obfuscator.obfuscate(userPrompt) : userPrompt;
+	const response = await instrumentedCompleteSimple(
+		resolved.model,
+		{
+			systemPrompt: [prompt.render(guidedGoalSystemPrompt)],
+			messages: [{ role: "user", content: [{ type: "text", text: promptText }], timestamp: Date.now() }],
+			tools: [RESPOND_TOOL],
+		},
+		{
+			apiKey: session.modelRegistry.resolver(resolved.model, session.sessionId),
+			signal: options.signal,
+			reasoning: toReasoningEffort(resolved.thinkingLevel),
+			toolChoice: { type: "tool", name: RESPOND_TOOL_NAME },
+		},
+		{ telemetry: resolveTelemetry(session.agent.telemetry, session.sessionId), oneshotKind: "guided_goal_setup" },
+	);
+
+	if (response.stopReason === "error") {
+		throw new Error(response.errorMessage ?? "guided goal request failed");
+	}
+	if (response.stopReason === "aborted") {
+		throw new Error("guided goal request aborted");
+	}
+
+	const call = extractToolCall(response, RESPOND_TOOL_NAME);
+	let result: GuidedGoalTurnResult;
+	if (call) {
+		result = parseGuidedGoalPayload(parseToolArguments(call.arguments));
+	} else {
+		const text = extractTextContent(response);
+		if (!text) {
+			throw new Error("guided goal returned an invalid response");
+		}
+		result = parseGuidedGoalPayload(parseJsonPayload(text));
+	}
+
+	// Reverse the obfuscation: restore any secret placeholders the model echoed back before the
+	// question/objective is shown or the goal is started.
+	if (!obfuscator?.hasSecrets()) return result;
+	if (result.kind === "question") {
+		return {
+			kind: "question",
+			question: obfuscator.deobfuscate(result.question),
+			objective: result.objective !== undefined ? obfuscator.deobfuscate(result.objective) : undefined,
+		};
+	}
+	return { kind: "ready", objective: obfuscator.deobfuscate(result.objective) };
+}

package/src/goals/state.ts

@@ -1,4 +1,4 @@
-import type { UsageStatistics } from "../session/session-manager";
+import type { UsageStatistics } from "../session/session-entries";
 
 export type GoalStatus = "active" | "paused" | "budget-limited" | "complete" | "dropped";
 

package/src/hindsight/transcript.ts

@@ -8,7 +8,7 @@
  */
 
 import type { AssistantMessage } from "@oh-my-pi/pi-ai";
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import type { HindsightMessage } from "./content";
 
 export interface ReadonlySessionManagerLike {