gentle-pi 2.5.0 → 2.6.0

package/lib/sdd-preflight.ts

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -11,13 +11,61 @@ export type { SddArtifactStore };
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
 const MANAGED_ASSETS_MANIFEST = "managed-assets.json";
+const MANAGED_ASSETS_LOCK = "managed-assets.lock";
 const MANAGED_ASSETS_SCHEMA_VERSION = 1;
+const MANAGED_ASSETS_LOCK_TIMEOUT_MS = 5_000;
+const MANAGED_ASSETS_LOCK_RETRY_MS = 25;
 const LEGACY_MANAGED_ASSET_MANIFESTS = Object.freeze([
 	{ path: join(ASSETS_DIR, "migrations", "managed-assets-v0.10.7.json"), version: "0.10.7" },
 	{ path: join(ASSETS_DIR, "migrations", "managed-assets-v0.13.json"), version: "0.13.0" },
 	{ path: join(ASSETS_DIR, "migrations", "managed-assets-v0.14.json"), version: "0.14.0" },
+	{ path: join(ASSETS_DIR, "migrations", "managed-assets-v2.5.0.json"), version: "2.5.0" },
 ]);
 
+const ASSET_OWNER_BY_KEY = Object.freeze({
+	"agents/gentle-ai-explore.md": "delegation",
+	"agents/gentle-ai-verify.md": "delegation",
+	"agents/gentle-ai-worker.md": "delegation",
+	"agents/jd-fix-agent.md": "review",
+	"agents/jd-judge-a.md": "review",
+	"agents/jd-judge-b.md": "review",
+	"agents/review-readability.md": "review",
+	"agents/review-reliability.md": "review",
+	"agents/review-resilience.md": "review",
+	"agents/review-risk.md": "review",
+	"agents/review-refuter.md": "review",
+	"agents/review-validator.md": "review",
+	"chains/4r-review.chain.md": "review",
+	"agents/sdd-apply.md": "sdd",
+	"agents/sdd-archive.md": "sdd",
+	"agents/sdd-design.md": "sdd",
+	"agents/sdd-explore.md": "sdd",
+	"agents/sdd-init.md": "sdd",
+	"agents/sdd-onboard.md": "sdd",
+	"agents/sdd-proposal.md": "sdd",
+	"agents/sdd-research.md": "sdd",
+	"agents/sdd-remediate.md": "sdd",
+	"agents/sdd-spec.md": "sdd",
+	"agents/sdd-status.md": "sdd",
+	"agents/sdd-sync.md": "sdd",
+	"agents/sdd-tasks.md": "sdd",
+	"agents/sdd-verify.md": "sdd",
+	"chains/sdd-full.chain.md": "sdd",
+	"chains/sdd-plan.chain.md": "sdd",
+	"chains/sdd-verify.chain.md": "sdd",
+	"gentle-ai/support/sdd-status-contract.md": "sdd",
+	"gentle-ai/support/strict-tdd.md": "sdd",
+	"gentle-ai/support/strict-tdd-verify.md": "sdd",
+} as const);
+
+export type PackageAssetOwner = (typeof ASSET_OWNER_BY_KEY)[keyof typeof ASSET_OWNER_BY_KEY];
+
+export function getPackageAssetOwner(ownershipKey: string): PackageAssetOwner | undefined {
+	return Object.hasOwn(ASSET_OWNER_BY_KEY, ownershipKey)
+		? ASSET_OWNER_BY_KEY[ownershipKey as keyof typeof ASSET_OWNER_BY_KEY]
+		: undefined;
+}
+
 function gentlePiAgentHome(): string {
 	return resolveGentlePiAgentHome();
 }
@@ -37,6 +85,24 @@ export type SddChainedPrStrategy =
 	| "force-chained";
 export type SddPreflightField = "executionMode" | "artifactStore" | "chainedPrStrategy" | "reviewBudgetLines";
 export const SDD_PREFLIGHT_FIELDS = ["executionMode", "artifactStore", "chainedPrStrategy", "reviewBudgetLines"] as const;
+// The parent dispatch and the process-spawn boundary share this exact shipped
+// inventory so a newly packaged SDD actor cannot bypass preflight transport.
+export const SHIPPED_SDD_AGENT_NAMES = Object.freeze([
+	"sdd-init",
+	"sdd-onboard",
+	"sdd-explore",
+	"sdd-research",
+	"sdd-proposal",
+	"sdd-spec",
+	"sdd-design",
+	"sdd-tasks",
+	"sdd-status",
+	"sdd-apply",
+	"sdd-verify",
+	"sdd-sync",
+	"sdd-archive",
+	"sdd-remediate",
+]);
 
 export interface SddPreflightPreferences {
 	executionMode: SddExecutionMode;
@@ -86,6 +152,20 @@ interface LegacyManagedAssetsManifest extends ManagedAssetsManifest {
 	packageVersion: string;
 }
 
+interface ManagedAssetsLockOwner {
+	schemaVersion: 1;
+	token: string;
+	pid: number;
+	createdAtMs: number;
+}
+
+/** @internal The hold option exists only to make process-lock regression tests deterministic. */
+interface PackageAssetInstallLockOptions {
+	timeoutMs?: number;
+	retryMs?: number;
+	holdLockMs?: number;
+}
+
 export const DEFAULT_SDD_PREFLIGHT: SddPreflightPreferences = Object.freeze({
 	executionMode: "auto",
 	artifactStore: "openspec",
@@ -198,6 +278,89 @@ function managedAssetHash(content: string): string {
 	return createHash("sha256").update(content).digest("hex");
 }
 
+function readManagedAssetsLockOwner(lockPath: string): ManagedAssetsLockOwner | undefined {
+	try {
+		if (!lstatSync(lockPath).isFile()) return undefined;
+		const parsed: unknown = JSON.parse(readFileSync(lockPath, "utf8"));
+		if (!isRecord(parsed) || parsed.schemaVersion !== 1 || typeof parsed.token !== "string" || parsed.token.length === 0 || !Number.isInteger(parsed.pid) || parsed.pid <= 0 || typeof parsed.createdAtMs !== "number" || !Number.isFinite(parsed.createdAtMs)) return undefined;
+		return parsed as ManagedAssetsLockOwner;
+	} catch {
+		return undefined;
+	}
+}
+
+function waitForManagedAssetsLock(milliseconds: number): void {
+	if (milliseconds <= 0) return;
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function normalizedLockDuration(value: number | undefined, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0
+		? Math.floor(value)
+		: fallback;
+}
+
+function acquireManagedAssetsLock(
+	agentHome: string,
+	options: PackageAssetInstallLockOptions = {},
+): { path: string; owner: ManagedAssetsLockOwner } {
+	const lockParent = join(agentHome, "gentle-ai");
+	const lockPath = join(lockParent, MANAGED_ASSETS_LOCK);
+	const timeoutMs = normalizedLockDuration(options.timeoutMs, MANAGED_ASSETS_LOCK_TIMEOUT_MS);
+	const retryMs = Math.max(1, normalizedLockDuration(options.retryMs, MANAGED_ASSETS_LOCK_RETRY_MS));
+	const deadline = Date.now() + timeoutMs;
+	mkdirSync(lockParent, { recursive: true });
+	for (;;) {
+		const owner: ManagedAssetsLockOwner = {
+			schemaVersion: 1,
+			token: randomUUID(),
+			pid: process.pid,
+			createdAtMs: Date.now(),
+		};
+		try {
+			writeFileSync(lockPath, JSON.stringify(owner), { encoding: "utf8", flag: "wx" });
+			return { path: lockPath, owner };
+		} catch (error) {
+			if (!isRecord(error) || error.code !== "EEXIST") throw error;
+			try {
+				if (!lstatSync(lockPath).isFile()) {
+					throw new Error(`Managed-assets lock path is unsafe and must be a regular file: ${lockPath}`);
+				}
+			} catch (inspectionError) {
+				if (isRecord(inspectionError) && inspectionError.code === "ENOENT") continue;
+				throw inspectionError;
+			}
+			if (Date.now() >= deadline) {
+				throw new Error(`Timed out acquiring managed-assets lock file ${lockPath}. Verify no installer is active before removing this exact lock file.`);
+			}
+			waitForManagedAssetsLock(retryMs);
+		}
+	}
+}
+
+function releaseManagedAssetsLock(lock: { path: string; owner: ManagedAssetsLockOwner }): void {
+	if (readManagedAssetsLockOwner(lock.path)?.token !== lock.owner.token) return;
+	try {
+		unlinkSync(lock.path);
+	} catch {
+		// An unreadable or replaced lock remains for an operator to inspect.
+	}
+}
+
+function withManagedAssetsLock<T>(
+	agentHome: string,
+	action: () => T,
+	options: PackageAssetInstallLockOptions | undefined,
+): T {
+	const lock = acquireManagedAssetsLock(agentHome, options);
+	try {
+		waitForManagedAssetsLock(normalizedLockDuration(options?.holdLockMs, 0));
+		return action();
+	} finally {
+		releaseManagedAssetsLock(lock);
+	}
+}
+
 function readLegacyManagedAssets(
 	path: string,
 	version: string,
@@ -289,10 +452,36 @@ function migrateLegacyAssetContent(
 	return updateAgentFrontmatterRouting(packagedContent, routingLines);
 }
 
+function replaceManagedAssetFileAtomically(path: string, content: string): void {
+	const temporaryPath = join(dirname(path), `.${randomUUID()}.tmp`);
+	let mode: number | undefined;
+	try {
+		const stat = lstatSync(path);
+		if (stat.isFile()) mode = stat.mode & 0o777;
+	} catch (error) {
+		if (!isRecord(error) || error.code !== "ENOENT") throw error;
+	}
+	try {
+		writeFileSync(temporaryPath, content, {
+			encoding: "utf8",
+			flag: "wx",
+			...(mode === undefined ? {} : { mode }),
+		});
+		renameSync(temporaryPath, path);
+	} finally {
+		try {
+			unlinkSync(temporaryPath);
+		} catch {
+			// A renamed or otherwise inaccessible temporary file needs no further action.
+		}
+	}
+}
+
 export function updatePackageManagedSddAgentOwnership(
 	installedPath: string,
 	previousContent: string,
 	nextContent: string,
+	lockOptions?: PackageAssetInstallLockOptions,
 ): boolean {
 	const agentHome = gentlePiAgentHome();
 	const relativePath = relative(join(agentHome, "agents"), installedPath);
@@ -305,19 +494,51 @@ export function updatePackageManagedSddAgentOwnership(
 		return false;
 	}
 	const ownershipKey = `agents/${relativePath.split(sep).join("/")}`;
-	const manifestPath = join(agentHome, "gentle-ai", MANAGED_ASSETS_MANIFEST);
-	const manifest = readManagedAssetsManifest(manifestPath);
-	if (manifest.assets[ownershipKey] !== managedAssetHash(previousContent)) {
-		return false;
-	}
-	try {
-		if (readFileSync(installedPath, "utf8") !== nextContent) return false;
-		manifest.assets[ownershipKey] = managedAssetHash(nextContent);
-		writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+	return withManagedAssetsLock(agentHome, () => {
+		const manifestPath = join(agentHome, "gentle-ai", MANAGED_ASSETS_MANIFEST);
+		const manifest = readManagedAssetsManifest(manifestPath);
+		if (manifest.assets[ownershipKey] !== managedAssetHash(previousContent)) {
+			return false;
+		}
+		const installedContent = readFileSync(installedPath, "utf8");
+		// The next-content branch preserves the prior internal caller contract:
+		// callers that wrote the file before this function still receive a managed
+		// manifest update. New callers take the previous-content branch below so
+		// the file and manifest update share this lock.
+		if (installedContent !== nextContent && installedContent !== previousContent) {
+			return false;
+		}
+		try {
+			if (installedContent === previousContent) {
+				replaceManagedAssetFileAtomically(installedPath, nextContent);
+			}
+			manifest.assets[ownershipKey] = managedAssetHash(nextContent);
+			replaceManagedAssetFileAtomically(
+				manifestPath,
+				JSON.stringify(manifest, null, 2),
+			);
+		} catch (error) {
+			try {
+				replaceManagedAssetFileAtomically(installedPath, previousContent);
+			} catch (rollbackError) {
+				throw new Error(
+					`Managed routing update failed and could not restore ${installedPath}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`,
+					{ cause: error },
+				);
+			}
+			throw error;
+		}
 		return true;
-	} catch {
-		return false;
-	}
+	}, lockOptions);
+}
+
+export function hasPackageAssetOwnerInstallation(owner: PackageAssetOwner): boolean {
+	const agentHome = gentlePiAgentHome();
+	const manifest = readManagedAssetsManifest(join(agentHome, "gentle-ai", MANAGED_ASSETS_MANIFEST));
+	return Object.keys(manifest.assets).some((key) => getPackageAssetOwner(key) === owner) ||
+		Object.entries(ASSET_OWNER_BY_KEY).some(([key, candidate]) =>
+			candidate === owner && existsSync(join(agentHome, key)),
+		);
 }
 
 export function isPackageManagedSddAsset(
@@ -411,8 +632,12 @@ function copyDirectoryFiles(
 	force: boolean,
 	manifest: ManagedAssetsManifest,
 	legacyAssetHashes: (() => Readonly<Record<string, readonly string[]>>) | undefined,
+	selected?: ReadonlySet<string>,
 ): { copied: number; skipped: number } {
 	if (!existsSync(sourceDir)) return { copied: 0, skipped: 0 };
+	if (selected && ![...selected].some(key => key.startsWith(`${ownershipPrefix}/`))) {
+		return { copied: 0, skipped: 0 };
+	}
 	mkdirSync(targetDir, { recursive: true });
 	let copied = 0;
 	let skipped = 0;
@@ -428,12 +653,13 @@ function copyDirectoryFiles(
 				force,
 				manifest,
 				legacyAssetHashes,
+				selected,
 			);
 			copied += child.copied;
 			skipped += child.skipped;
 			continue;
 		}
-		if (!entry.isFile()) continue;
+		if (!entry.isFile() || (selected && !selected.has(ownershipKey))) continue;
 		const source = readFileSync(sourcePath, "utf8");
 		let nextSource = source;
 		if (existsSync(targetPath)) {
@@ -476,6 +702,9 @@ function copyDirectoryFiles(
 				delete manifest.assets[ownershipKey];
 				skipped += 1;
 				continue;
+			} else if (ownershipKey === "agents/sdd-research.md" && installedContent !== undefined) {
+				// Keep routing adopted by the legacy migration on subsequent refreshes.
+				nextSource = migrateLegacyAssetContent(ownershipKey, installedContent, source);
 			}
 		}
 		writeFileSync(targetPath, nextSource);
@@ -503,9 +732,11 @@ const RETIRED_MANAGED_ASSETS = Object.freeze([
 function removeRetiredManagedAssets(
 	agentHome: string,
 	manifest: ManagedAssetsManifest,
+	selected?: ReadonlySet<string>,
 ): void {
 	let legacyHashes: Record<string, readonly string[]> | undefined;
 	for (const ownershipKey of RETIRED_MANAGED_ASSETS) {
+		if (selected && !selected.has(ownershipKey)) continue;
 		const installedPath = join(agentHome, ...ownershipKey.split("/"));
 		if (!existsSync(installedPath)) {
 			delete manifest.assets[ownershipKey];
@@ -536,52 +767,80 @@ function removeRetiredManagedAssets(
 	}
 }
 
+// Legacy all-owner entry point retained for compatibility.
+// Owner-specific commands and SDD preflight use installPackageAssets directly.
 export function installSddAssets(
+	cwd: string,
+	force: boolean,
+): { agents: number; chains: number; support: number; skipped: number } {
+	return installPackageAssets(cwd, force);
+}
+
+export function installPackageAssets(
 	_cwd: string,
 	force: boolean,
+	owners?: readonly PackageAssetOwner[],
+	lockOptions?: PackageAssetInstallLockOptions,
 ): { agents: number; chains: number; support: number; skipped: number } {
 	const agentHome = gentlePiAgentHome();
-	const manifestPath = join(agentHome, "gentle-ai", MANAGED_ASSETS_MANIFEST);
-	let legacyAssetHashes: (() => Readonly<Record<string, readonly string[]>>) | undefined;
-	if (force) {
-		let cachedLegacyAssetHashes: Record<string, readonly string[]> | undefined;
-		legacyAssetHashes = () =>
-			(cachedLegacyAssetHashes ??= readLegacyManagedAssetHashes());
-	}
-	const manifest = readManagedAssetsManifest(manifestPath);
-	removeRetiredManagedAssets(agentHome, manifest);
-	const agents = copyDirectoryFiles(
-		join(ASSETS_DIR, "agents"),
-		join(agentHome, "agents"),
-		"agents",
-		force,
-		manifest,
-		legacyAssetHashes,
-	);
-	const chains = copyDirectoryFiles(
-		join(ASSETS_DIR, "chains"),
-		join(agentHome, "chains"),
-		"chains",
-		force,
-		manifest,
-		legacyAssetHashes,
-	);
-	const support = copyDirectoryFiles(
-		join(ASSETS_DIR, "support"),
-		join(agentHome, "gentle-ai", "support"),
-		"gentle-ai/support",
-		force,
-		manifest,
-		legacyAssetHashes,
-	);
-	mkdirSync(dirname(manifestPath), { recursive: true });
-	writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
-	return {
-		agents: agents.copied,
-		chains: chains.copied,
-		support: support.copied,
-		skipped: agents.skipped + chains.skipped + support.skipped,
-	};
+	return withManagedAssetsLock(agentHome, () => {
+		const selected = owners === undefined ? undefined : new Set(
+			Object.entries(ASSET_OWNER_BY_KEY).filter(([, owner]) => owners.includes(owner)).map(([key]) => key),
+		);
+		const manifestPath = join(agentHome, "gentle-ai", MANAGED_ASSETS_MANIFEST);
+		let legacyAssetHashes: (() => Readonly<Record<string, readonly string[]>>) | undefined;
+		if (force) {
+			let cachedLegacyAssetHashes: Record<string, readonly string[]> | undefined;
+			legacyAssetHashes = () =>
+				(cachedLegacyAssetHashes ??= readLegacyManagedAssetHashes());
+		}
+		const manifest = readManagedAssetsManifest(manifestPath);
+		removeRetiredManagedAssets(agentHome, manifest, selected);
+		const agents = copyDirectoryFiles(
+			join(ASSETS_DIR, "agents"),
+			join(agentHome, "agents"),
+			"agents",
+			force,
+			manifest,
+			legacyAssetHashes,
+			selected,
+		);
+		const chains = copyDirectoryFiles(
+			join(ASSETS_DIR, "chains"),
+			join(agentHome, "chains"),
+			"chains",
+			force,
+			manifest,
+			legacyAssetHashes,
+			selected,
+		);
+		const support = copyDirectoryFiles(
+			join(ASSETS_DIR, "support"),
+			join(agentHome, "gentle-ai", "support"),
+			"gentle-ai/support",
+			force,
+			manifest,
+			legacyAssetHashes,
+			selected,
+		);
+		mkdirSync(dirname(manifestPath), { recursive: true });
+		writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+		return {
+			agents: agents.copied,
+			chains: chains.copied,
+			support: support.copied,
+			skipped: agents.skipped + chains.skipped + support.skipped,
+		};
+	}, lockOptions);
+}
+
+function hasAffirmativeSddIntent(text: string): boolean {
+	// Natural-language routing must not depend on a closed list of complete
+	// phrases. An SDD mention becomes an invocation only with an imperative,
+	// request, or first-person intent marker; a neutral statement such as
+	// "I use SDD sometimes" remains ordinary conversation.
+	if (!/\bsdd\b/i.test(text)) return false;
+	return /(?:\b(?:please|por\s+favor)\b|\b(?:want|need|would\s+like|let'?s|quiero|queremos|necesito|quisiera|me\s+gustar[ií]a|vamos|vayamos|hagamos|usemos)\b|^(?:use|run|start|build|create|implement|handle|make|usa|usá|corre|corré|arranca|arrancá|inicia|iniciá|empeza|empezá|hacelo|hazlo|hacerlo)\b)/i.test(text);
 }
 
 export function isSddPreflightTrigger(text: string): boolean {
@@ -589,19 +848,12 @@ export function isSddPreflightTrigger(text: string): boolean {
 	if (/^\/(?:gentle-)?sdd(?:[-:][^\s]*)?(?:\s|$)/i.test(trimmed)) return true;
 	if (/[?？]\s*$/.test(trimmed)) return false;
 	if (
-		/\b(?:don't|do\s+not|not\s+use|never\s+use|without\s+using|sin\s+usar|no\s+(?:quiero|queremos|vamos\s+a)?\s*usar)\s+sdd\b/i.test(
-			trimmed,
-		)
+		/(?:\b(?:don't|do\s+not|never)\b|\bnot\s+(?:want|need|plan(?:ning)?|intend|use|using)\b)[^.!?\n]{0,80}\bsdd\b/i.test(trimmed) ||
+		/\b(?:sin\s+usar|no\s+(?:quiero|queremos|necesito|necesitamos|quisiera|quisiéramos|vamos\s+a|pienso|planeo|usar))\b[^.!?\n]{0,80}\bsdd\b/i.test(trimmed)
 	) {
 		return false;
 	}
-	return [
-		/^(?:please\s+)?(?:use|run|start)\s+(?:the\s+|an?\s+)?sdd(?:\s+(?:flow|process|workflow|plan))?\b/i,
-		/^(?:please\s+)?(?:do|handle|implement)\b.+\b(?:with|using)\s+(?:the\s+|an?\s+)?sdd\b/i,
-		/^(?:por\s+favor[\s,]+)?(?:vamos|vayamos)\s+con\s+(?:el\s+)?sdd\b/i,
-		/^(?:por\s+favor[\s,]+)?(?:usa|usá|usemos|corre|corré|arranca|arrancá|inicia|iniciá|empeza|empezá)\s+(?:el\s+)?sdd\b/i,
-		/^(?:por\s+favor[\s,]+)?(?:hacelo|hazlo|hacerlo)\s+(?:con|usando)\s+(?:el\s+)?sdd\b/i,
-	].some((pattern) => pattern.test(trimmed));
+	return hasAffirmativeSddIntent(trimmed);
 }
 
 export function sddPreflightSessionKey(ctx: ExtensionContext): string {
@@ -646,13 +898,23 @@ export async function collectSddPreflightPreferences(
 	engramAvailable: boolean,
 	options: SddPreflightResolutionOptions = {},
 ): Promise<SddPreflightPreferences> {
-	const persistedPrompted = options.persisted?.prompted === true;
+	// Disk preferences suggest values; they never carry current-session consent.
 	const allowExceptionOk = options.acceptSizeException === true;
 	const persisted = normalizedSelections(options.persisted, engramAvailable, allowExceptionOk);
 	const resolved: Partial<Record<SddPreflightField, unknown>> = { ...persisted };
-	let prompted = persistedPrompted;
+	let prompted = false;
 	let sizeExceptionAccepted = allowExceptionOk && persisted.chainedPrStrategy === "exception-ok";
 	const promptFields = new Set(options.promptFields ?? []);
+	// RPC is headless even though Pi exposes functional dialog methods there.
+	if (ctx.hasUI && ctx.mode !== "rpc" && promptFields.size === 0) {
+		const suggestions = { ...DEFAULT_SDD_PREFLIGHT, ...persisted };
+		ctx.ui.notify(`SDD session suggestions: mode=${suggestions.executionMode}; artifacts=${suggestions.artifactStore}; delivery=${suggestions.chainedPrStrategy}; budget=${suggestions.reviewBudgetLines}. Saved preferences are not session consent.`, "info");
+		if (typeof ctx.ui.select !== "function") throw new Error("SDD preflight confirmation UI unavailable; no session consent recorded.");
+		const answer = await ctx.ui.select("Confirm SDD session preflight", ["Confirm", "Change choices"]);
+		if (answer === "Confirm") prompted = true;
+		else if (answer === "Change choices") for (const field of SDD_PREFLIGHT_FIELDS) promptFields.add(field);
+		else throw new Error("SDD preflight cancelled; no session consent recorded.");
+	}
 
 	const usePromptedValue = (
 		field: SddPreflightField,
@@ -671,15 +933,23 @@ export async function collectSddPreflightPreferences(
 		read: () => Promise<unknown>,
 		enabled = true,
 	): Promise<void> => {
-		if (ctx.hasUI && enabled && promptFields.has(field)) {
-			usePromptedValue(field, await read());
+		if (ctx.hasUI && ctx.mode !== "rpc" && enabled && promptFields.has(field)) {
+			const value = await read();
+			if (normalizedSelections({ [field]: value }, engramAvailable, allowExceptionOk)[field] === undefined) {
+				throw new Error("SDD preflight cancelled or invalid; no session consent recorded.");
+			}
+			usePromptedValue(field, value);
 		}
 	};
 	const artifactOptions = engramAvailable ? ["openspec", "engram", "hybrid"] : ["openspec"];
-	await promptField("executionMode", () => ctx.ui.select("SDD execution mode", ["interactive", "auto"]));
-	await promptField("artifactStore", () => ctx.ui.select("SDD artifact store", artifactOptions), artifactOptions.length > 1);
-	await promptField("chainedPrStrategy", () => ctx.ui.select("SDD delivery strategy", ["ask-on-risk", "auto-chain", "single-pr"]));
-	await promptField("reviewBudgetLines", () => ctx.ui.input("SDD review budget lines", String(DEFAULT_SDD_PREFLIGHT.reviewBudgetLines)));
+	const suggestedFirst = (field: SddPreflightField, values: string[]): string[] => {
+		const suggested = String(resolved[field] ?? DEFAULT_SDD_PREFLIGHT[field]);
+		return values.includes(suggested) ? [suggested, ...values.filter(value => value !== suggested)] : values;
+	};
+	await promptField("executionMode", () => ctx.ui.select("SDD execution mode", suggestedFirst("executionMode", ["interactive", "auto"])));
+	await promptField("artifactStore", () => ctx.ui.select("SDD artifact store", suggestedFirst("artifactStore", artifactOptions)), artifactOptions.length > 1);
+	await promptField("chainedPrStrategy", () => ctx.ui.select("SDD delivery strategy", suggestedFirst("chainedPrStrategy", ["ask-on-risk", "auto-chain", "single-pr"])));
+	await promptField("reviewBudgetLines", () => ctx.ui.input("SDD review budget lines", String(resolved.reviewBudgetLines ?? DEFAULT_SDD_PREFLIGHT.reviewBudgetLines)));
 
 	const resolvedValue = <T>(field: SddPreflightField, fallback: T): T =>
 		(resolved[field] as T | undefined) ?? fallback;
@@ -694,6 +964,16 @@ export async function collectSddPreflightPreferences(
 	};
 }
 
+export function isParentConfirmedSddPreflightContext(context: unknown): context is string {
+	if (typeof context !== "string") return false;
+	return /^## SDD Session Preflight\n(?:These SDD preferences are explicit current-session choices\. Reuse them unless the user explicitly changes them\.|These SDD preferences are canonical defaults or persisted choices\. Treat them as authoritative; do not revisit dependent decisions unless a genuine human-control gate is reached\.)\n- Execution mode: (?:interactive|auto)\n- Artifact store: (?:openspec|engram|hybrid|none)(?: \(Engram unavailable in this session\))?\n- Delivery strategy: (?:ask-on-risk|auto-chain|single-pr|exception-ok)\n- Delivery strategy domain: `ask-on-risk` \| `auto-chain` \| `single-pr` \| `exception-ok`\n- Review budget: [1-9]\d* changed lines \(400 is the canonical threshold unless explicitly changed\)\n- Chain strategy: deferred until chaining is selected\./.test(context);
+}
+
+export function extractParentConfirmedSddPreflightContext(context: unknown): string | undefined {
+	if (!isParentConfirmedSddPreflightContext(context)) return undefined;
+	return context.split("\n\n", 1)[0];
+}
+
 export function renderSddPreflightPrompt(prefs: SddPreflightPreferences): string {
 	const deliveryStrategy = normalizeSddChainedPrStrategy(
 		prefs.chainedPrStrategy,
@@ -733,6 +1013,12 @@ export async function ensureSddPreflight(
 	callbacks: SddPreflightCallbacks,
 	resolutionOptions: SddPreflightResolutionOptions = {},
 ): Promise<SddPreflightPreferences> {
+	// `collectSddPreflightPreferences` remains a pure suggestion resolver for
+	// callers that need to render options. Persisting or promoting those options
+	// is parent-only: an RPC child must consume the transported rendered block.
+	if (ctx.mode === "rpc") {
+		throw new Error("SDD preflight must be resolved by the parent; an RPC child cannot originate or persist defaults.");
+	}
 	const sessionKey = sddPreflightSessionKey(ctx);
 	const existing = sddPreflightBySession.get(sessionKey);
 	if (existing && !(resolutionOptions.promptFields?.length ?? 0)) return existing;
@@ -747,7 +1033,7 @@ export async function ensureSddPreflight(
 		});
 		const result =
 			(await callbacks.installAssets?.(ctx.cwd)) ??
-			installSddAssets(ctx.cwd, false);
+			installPackageAssets(ctx.cwd, false, ["sdd"]);
 		const modelResult = (await callbacks.applyModelConfig?.(ctx.cwd)) ?? {
 			updated: 0,
 			skipped: 0,
@@ -788,11 +1074,6 @@ export function getSddPreflightPreferences(
 	const sessionKey = sddPreflightSessionKey(ctx);
 	const cached = sddPreflightBySession.get(sessionKey);
 	if (cached) return cached;
-	// Cache miss: check the durable disk store (survives restarts and non-SDD agent starts)
-	const persisted = readSddPreflightFromDisk(ctx.cwd);
-	if (persisted) {
-		sddPreflightBySession.set(sessionKey, persisted);
-		return persisted;
-	}
+	// Only ensureSddPreflight may promote disk suggestions to resolved session choices.
 	return undefined;
 }