gentle-pi 3.2.1 → 3.4.0

package/lib/questionnaire/validate.ts

@@ -0,0 +1,141 @@
+import {
+	CUSTOM_ROW_LABEL,
+	MAX_HEADER_LENGTH,
+	MAX_LABEL_LENGTH,
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	type QuestionParams,
+} from "./schema.ts";
+
+/**
+ * A single questionnaire validation violation, keyed by `code` so callers can
+ * branch without parsing the human-readable message.
+ */
+export type QuestionnaireError =
+	| { code: "no_questions"; message: string }
+	| { code: "empty_options"; message: string; questionIndex: number }
+	| { code: "option_count"; message: string; questionIndex: number; count: number }
+	| { code: "too_many_questions"; message: string; count: number }
+	| { code: "duplicate_question"; message: string; questionIndex: number }
+	| { code: "duplicate_option_label"; message: string; questionIndex: number; optionIndex: number; label: string }
+	| { code: "label_too_long"; message: string; questionIndex: number; optionIndex: number; length: number }
+	| { code: "header_too_long"; message: string; questionIndex: number; length: number }
+	| { code: "reserved_label"; message: string; questionIndex: number; optionIndex: number; label: string };
+
+/**
+ * Validate questionnaire parameters and return the first violation in a fixed
+ * precedence order, or `undefined` when the parameters are valid.
+ *
+ * Precedence: no questions, empty options, option count, question count,
+ * duplicate question text, duplicate option label, label length, header
+ * length, then reserved custom-row labels.
+ */
+export function validateQuestionnaire(params: QuestionParams): QuestionnaireError | undefined {
+	const questions = Array.isArray(params?.questions) ? params.questions : [];
+
+	if (questions.length === 0) {
+		return { code: "no_questions", message: "At least one question is required." };
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		if (!Array.isArray(question?.options) || question.options.length === 0) {
+			return {
+				code: "empty_options",
+				message: `Question ${questionIndex + 1} must declare at least one option.`,
+				questionIndex,
+			};
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		const count = question.options.length;
+		if (count < MIN_OPTIONS || count > MAX_OPTIONS) {
+			return {
+				code: "option_count",
+				message: `Question ${questionIndex + 1} must have between ${MIN_OPTIONS} and ${MAX_OPTIONS} options, received ${count}.`,
+				questionIndex,
+				count,
+			};
+		}
+	}
+
+	if (questions.length > MAX_QUESTIONS) {
+		return {
+			code: "too_many_questions",
+			message: `A questionnaire accepts at most ${MAX_QUESTIONS} questions, received ${questions.length}.`,
+			count: questions.length,
+		};
+	}
+
+	const seenQuestions = new Set<string>();
+	for (const [questionIndex, question] of questions.entries()) {
+		if (seenQuestions.has(question.question)) {
+			return {
+				code: "duplicate_question",
+				message: `Question ${questionIndex + 1} duplicates an earlier question text.`,
+				questionIndex,
+			};
+		}
+		seenQuestions.add(question.question);
+	}
+
+	// Checked after duplicate questions so a repeated question points at the
+	// duplicate itself rather than one of its option labels.
+	for (const [questionIndex, question] of questions.entries()) {
+		const seenLabels = new Set<string>();
+		for (const [optionIndex, option] of question.options.entries()) {
+			if (seenLabels.has(option.label)) {
+				return {
+					code: "duplicate_option_label",
+					message: `Question ${questionIndex + 1} option ${optionIndex + 1} duplicates the label "${option.label}".`,
+					questionIndex,
+					optionIndex,
+					label: option.label,
+				};
+			}
+			seenLabels.add(option.label);
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		for (const [optionIndex, option] of question.options.entries()) {
+			if (option.label.length > MAX_LABEL_LENGTH) {
+				return {
+					code: "label_too_long",
+					message: `Question ${questionIndex + 1} option ${optionIndex + 1} label exceeds ${MAX_LABEL_LENGTH} characters.`,
+					questionIndex,
+					optionIndex,
+					length: option.label.length,
+				};
+			}
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		if (question.header.length > MAX_HEADER_LENGTH) {
+			return {
+				code: "header_too_long",
+				message: `Question ${questionIndex + 1} header exceeds ${MAX_HEADER_LENGTH} characters.`,
+				questionIndex,
+				length: question.header.length,
+			};
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		for (const [optionIndex, option] of question.options.entries()) {
+			if (option.label === "Other" || option.label === CUSTOM_ROW_LABEL) {
+				return {
+					code: "reserved_label",
+					message: `Question ${questionIndex + 1} option ${optionIndex + 1} uses the reserved label "${option.label}".`,
+					questionIndex,
+					optionIndex,
+					label: option.label,
+				};
+			}
+		}
+	}
+
+	return undefined;
+}

package/lib/review-candidate-view-owner.ts

@@ -27,6 +27,21 @@ const WINDOWS_SYSTEM = "S-1-5-18";
 const WINDOWS_ADMINISTRATORS = "S-1-5-32-544";
 const WINDOWS_SYSTEM_DIRECTORY = "\\\\?\\GLOBALROOT\\SystemRoot\\System32";
 
+// Cold Windows runners occasionally exceed the bounded 5-second probe timeout
+// on first process start (whoami/PowerShell/icacls). One bounded retry of an
+// idempotent system probe recovers that transient; authority validation is
+// never retried or weakened because it happens after the probe returns.
+const TRANSIENT_WINDOWS_PROBE_CODES = new Set(["ETIMEDOUT", "EAGAIN", "EBUSY"]);
+
+export function withWindowsSystemProbeRetry<T>(probe: () => T): T {
+	try {
+		return probe();
+	} catch (error) {
+		if (!TRANSIENT_WINDOWS_PROBE_CODES.has((error as NodeJS.ErrnoException | undefined)?.code ?? "")) throw error;
+		return probe();
+	}
+}
+
 function windowsSystemExecutable(name: "whoami.exe" | "icacls.exe" | "WindowsPowerShell\\v1.0\\powershell.exe"): string {
 	try {
 		return realpathSync.native(join(WINDOWS_SYSTEM_DIRECTORY, name));
@@ -36,7 +51,7 @@ function windowsSystemExecutable(name: "whoami.exe" | "icacls.exe" | "WindowsPow
 }
 
 function windowsUserSid(): string {
-	const output = execFileSync(windowsSystemExecutable("whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+	const output = withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true }));
 	const matches = output.match(/S-\d+(?:-\d+)+/gi) ?? [];
 	if (matches.length !== 1) throw new Error("Windows user SID is unavailable");
 	return matches[0]!.toUpperCase();
@@ -45,7 +60,7 @@ function windowsUserSid(): string {
 function windowsLocalAdministratorSid(): string {
 	const script = "$ErrorActionPreference='Stop';$descriptor=New-Object System.Security.AccessControl.RawSecurityDescriptor 'D:(A;;FA;;;LA)';$descriptor.DiscretionaryAcl[0].SecurityIdentifier.Value";
 	const systemRoot = dirname(dirname(windowsSystemExecutable("whoami.exe")));
-	const output = execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot } });
+	const output = withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot } }));
 	const matches = output.match(/S-\d+(?:-\d+)+/gi) ?? [];
 	if (matches.length !== 1 || !isWindowsSid(matches[0]!)) throw new Error("Windows local Administrator SID is unavailable");
 	return matches[0]!.toUpperCase();
@@ -55,7 +70,7 @@ function windowsDacl(path: string): string {
 	const archive = `.gentle-ai-acl-${randomUUID()}.txt`;
 	const archivePath = join(dirname(path), archive);
 	try {
-		execFileSync(windowsSystemExecutable("icacls.exe"), [path, "/save", archive, "/c"], { cwd: dirname(path), encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+		withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("icacls.exe"), [path, "/save", archive, "/c"], { cwd: dirname(path), encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true }));
 		const sddl = readFileSync(archivePath, "utf16le").match(/D:[^\r\n]+/)?.[0];
 		if (sddl === undefined) throw new Error("Windows DACL is unavailable");
 		return sddl;
@@ -151,7 +166,7 @@ function windowsOwnerSid(path: string, kind: WindowsObjectKind): string {
 	const systemRoot = dirname(dirname(windowsSystemExecutable("whoami.exe")));
 	let output: string;
 	try {
-		output = execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_OWNER_PATH: path } });
+		output = withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_OWNER_PATH: path } }));
 	} catch {
 		throw new WindowsOwnerValidationError();
 	}
@@ -175,7 +190,7 @@ function enforcePrivateWindowsDacl(path: string, identity: WindowsAclIdentity =
 	const sddl = `D:P(A;OICI;FA;;;${user})(A;OICI;FA;;;${WINDOWS_SYSTEM})(A;OICI;FA;;;${WINDOWS_ADMINISTRATORS})`;
 	const script = "$ErrorActionPreference='Stop';$acl=New-Object System.Security.AccessControl.DirectorySecurity;$acl.SetSecurityDescriptorSddlForm($env:GENTLE_PI_CANDIDATE_ACL_SDDL,[System.Security.AccessControl.AccessControlSections]::Access);[System.IO.Directory]::SetAccessControl($env:GENTLE_PI_CANDIDATE_ACL_PATH,$acl)";
 	const systemRoot = dirname(dirname(windowsSystemExecutable("whoami.exe")));
-	execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_ACL_PATH: path, GENTLE_PI_CANDIDATE_ACL_SDDL: sddl } });
+	withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_ACL_PATH: path, GENTLE_PI_CANDIDATE_ACL_SDDL: sddl } }));
 	assertPrivateWindowsDacl(path, "directory", true, identity);
 }
 

package/lib/review-candidate-view.ts

@@ -634,6 +634,13 @@ function makeWritableForCleanup(path: string): void {
 	chmodSync(path, 0o644);
 }
 
+function candidateOwnerPreparationError(error: unknown): CandidateViewError {
+	// Surface the bounded errno of the underlying failure directly in the
+	// message so CI logs are self-diagnosing without TAP printing the cause.
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return new CandidateViewError(`candidate view owner preparation failed${typeof code === "string" && code ? ` (${code})` : ""}`, "candidate-owner-preparation-failed", undefined, { cause: error });
+}
+
 function candidateViewParent(commonDir: string, platform: NodeJS.Platform): string {
 	const control = join(commonDir, "gentle-ai");
 	mkdirSync(control, { recursive: true, mode: 0o700 });
@@ -646,7 +653,7 @@ function candidateViewParent(commonDir: string, platform: NodeJS.Platform): stri
 	try {
 		return prepareCandidateOwnerParent(commonDir, platform);
 	} catch (error) {
-		throw new CandidateViewError("candidate view owner preparation failed", "candidate-owner-preparation-failed", undefined, { cause: error });
+		throw candidateOwnerPreparationError(error);
 	}
 }
 
@@ -916,7 +923,7 @@ function materializeCandidateView(request: CreateCandidateViewRequest, executor:
 		try {
 			owner = createCandidateOwner(canonicalCommonDir, root, platform);
 		} catch (error) {
-			throw new CandidateViewError("candidate view owner preparation failed", "candidate-owner-preparation-failed", undefined, { cause: error });
+			throw candidateOwnerPreparationError(error);
 		}
 		// The worktree is created under the same try/catch cleanup boundary as
 		// the read-tree materialization that follows. addUnbornWorktree's