ultimate-pi 0.24.0 → 0.25.0

package/.pi/lib/harness-remediation.ts

@@ -0,0 +1,79 @@
+/**
+ * Review remediation classification — shared by run-context and repair-brief.
+ */
+
+export type RemediationClass =
+	| "pass"
+	| "implementation_gap"
+	| "plan_gap"
+	| "rollback"
+	| "inconclusive";
+
+export interface ReviewOutcomeLike {
+	schema_version?: string;
+	status?: string;
+	remediation_class?: RemediationClass | string;
+	recommended_next?: string;
+}
+
+export interface EvalVerdictLike {
+	status?: string;
+	recommended_action?: string;
+	failed_checks?: string[];
+}
+
+/** Infer remediation when parent skipped Phase 6 but eval-verdict exists on disk. */
+export function remediationClassFromEvalVerdict(
+	verdict: EvalVerdictLike | null,
+): RemediationClass | null {
+	if (!verdict) return null;
+	const status = (verdict.status ?? "").toLowerCase();
+	if (status === "pass") return "pass";
+	const action = (verdict.recommended_action ?? "").toLowerCase();
+	if (
+		action === "replan" ||
+		action.includes("revise") ||
+		action.includes("plan")
+	) {
+		return "plan_gap";
+	}
+	if (action === "rollback" || action.includes("rollback")) {
+		return "rollback";
+	}
+	if (
+		action === "steer" ||
+		action === "repair" ||
+		action.includes("implement")
+	) {
+		return "implementation_gap";
+	}
+	const joined = Array.isArray(verdict.failed_checks)
+		? verdict.failed_checks.join(" ").toLowerCase()
+		: "";
+	if (
+		joined.includes("scope_minimization") ||
+		joined.includes("scope_drift") ||
+		joined.includes("replan")
+	) {
+		return "plan_gap";
+	}
+	if (status === "fail") return "inconclusive";
+	return null;
+}
+
+export function recommendedNextForRemediation(
+	remediation: RemediationClass,
+): string {
+	switch (remediation) {
+		case "pass":
+			return "/harness-policy-status";
+		case "implementation_gap":
+			return "/harness-steer";
+		case "plan_gap":
+			return "/harness-plan (mode: revise)";
+		case "rollback":
+			return "/harness-incident";
+		default:
+			return "/harness-review";
+	}
+}

package/.pi/lib/harness-repair-brief.ts

@@ -4,10 +4,10 @@
 
 import { join } from "node:path";
 import {
-	harnessRunsRoot,
 	type RemediationClass,
 	remediationClassFromEvalVerdict,
-} from "./harness-run-context.js";
+} from "./harness-remediation.js";
+import { harnessRunsRoot } from "./harness-subagent-submit-path.js";
 import { readYamlFile, writeYamlFile } from "./harness-yaml.js";
 
 const REPAIR_BRIEF_SCHEMA = "1.0.0";

package/.pi/lib/harness-review-parallel.ts

@@ -0,0 +1,18 @@
+/**
+ * Risk-based default for parallel review evaluator ∥ adversary.
+ */
+
+export interface ReviewParallelOpts {
+	quick?: boolean;
+	steerAttempt?: number;
+}
+
+export function isHarnessReviewParallelEnabled(
+	opts?: ReviewParallelOpts,
+): boolean {
+	if (process.env.HARNESS_REVIEW_PARALLEL === "0") return false;
+	if (process.env.HARNESS_REVIEW_PARALLEL === "1") return true;
+	if (opts?.quick) return false;
+	if ((opts?.steerAttempt ?? 0) >= 2) return false;
+	return true;
+}

package/.pi/lib/harness-run-context.ts

@@ -12,6 +12,7 @@ import {
 	readFile,
 	realpath,
 	stat,
+	unlink,
 	writeFile,
 } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
@@ -20,7 +21,23 @@ import {
 	PLAN_APPROVE_OPTION,
 	PLAN_CANCEL_OPTION,
 } from "./ask-user/policy.js";
+import {
+	type RemediationClass,
+	type ReviewOutcomeLike,
+	recommendedNextForRemediation,
+	remediationClassFromEvalVerdict,
+} from "./harness-remediation.js";
 import { readYamlFile, writeYamlFile } from "./harness-yaml.js";
+
+export type {
+	RemediationClass,
+	ReviewOutcomeLike,
+} from "./harness-remediation.js";
+export {
+	recommendedNextForRemediation,
+	remediationClassFromEvalVerdict,
+} from "./harness-remediation.js";
+
 import { readTaskClarificationDoc } from "./plan-task-clarification.js";
 
 export { isPlanApprovalAskUser } from "./ask-user/policy.js";
@@ -969,6 +986,25 @@ export function getLatestRunContext(
 	entries: unknown[],
 ): HarnessRunContext | null {
 	for (let i = entries.length - 1; i >= 0; i--) {
+		const clearEntry = entries[i] as SessionEntryLike;
+		if (
+			clearEntry.type === "custom" &&
+			clearEntry.customType === "harness-clear-result"
+		) {
+			const clearData = clearEntry.data as
+				| {
+						approved?: boolean;
+						active_cleared?: boolean;
+						cleared_all?: boolean;
+				  }
+				| undefined;
+			if (
+				clearData?.approved === true &&
+				(clearData.active_cleared === true || clearData.cleared_all === true)
+			) {
+				return null;
+			}
+		}
 		const entry = entries[i] as SessionEntryLike;
 		if (entry.type !== "custom" || entry.customType !== "harness-run-context")
 			continue;
@@ -1067,6 +1103,17 @@ export async function loadProjectActiveRun(
 	}
 }
 
+export async function deleteProjectActiveRun(
+	projectRoot: string,
+): Promise<boolean> {
+	try {
+		await unlink(activeRunPointerPath(projectRoot));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 export async function saveProjectActiveRun(
 	ctx: HarnessRunContext,
 ): Promise<void> {
@@ -1107,6 +1154,52 @@ export function isStaleActiveRunPointer(
 	return ageMs > activeRunTtlHours() * 60 * 60 * 1000;
 }
 
+export interface ActiveRunOwnershipConflict {
+	runId: string;
+	ownerPiSessionId: string;
+}
+
+/** True when another Pi session owns a non-stale active run on disk. */
+export async function findActiveRunOwnershipConflict(
+	projectRoot: string,
+	sessionId: string,
+): Promise<ActiveRunOwnershipConflict | null> {
+	const pointer = await loadProjectActiveRun(projectRoot);
+	if (!pointer || isStaleActiveRunPointer(pointer, projectRoot)) return null;
+	if (pointer.owner_pi_session_id === sessionId) return null;
+	const disk = await loadRunContextFromDisk(pointer.run_id, projectRoot);
+	if (!disk || disk.status !== "active") return null;
+	return {
+		runId: pointer.run_id,
+		ownerPiSessionId: pointer.owner_pi_session_id,
+	};
+}
+
+/** QA smoke: drop stale harness-qa-live ownership left by interrupted live QA runs. */
+export async function releaseForeignQaRunOwnership(
+	projectRoot: string,
+	sessionId: string,
+): Promise<boolean> {
+	if (process.env.HARNESS_QA_SMOKE !== "1") return false;
+	const pointer = await loadProjectActiveRun(projectRoot);
+	if (!pointer || pointer.owner_pi_session_id === sessionId) return false;
+	if (!pointer.owner_pi_session_id.startsWith("harness-qa-live-")) {
+		return false;
+	}
+	const disk = await loadRunContextFromDisk(pointer.run_id, projectRoot);
+	if (disk && disk.status === "active") {
+		await saveRunContextToDisk({
+			...disk,
+			status: "aborted",
+			last_outcome: "abandoned",
+			last_completed_step: "abort",
+			updated_at: nowIso(),
+		});
+	}
+	await deleteProjectActiveRun(projectRoot);
+	return true;
+}
+
 export interface CrossSessionResumeInfo {
 	runId: string;
 	resumeCommand: string;
@@ -1937,8 +2030,32 @@ export function isHarnessBootstrapPrompt(prompt: string): boolean {
 }
 
 export function hasHarnessAbortSignal(prompt: string): boolean {
-	const p = prompt.toLowerCase();
-	return p.includes("/harness-abort") || p.includes("harness-abort");
+	const slice = userVisiblePromptSlice(prompt);
+	for (const line of slice.split("\n")) {
+		const parsed = parseHarnessSlashInput(line.trim());
+		if (parsed?.command === "harness-abort") return true;
+	}
+	return false;
+}
+
+/** Slash command line for AGT prompt defense — not expanded prompt template bodies. */
+export function harnessSlashCommandLineForPolicy(
+	prompt: string,
+	entries?: unknown[],
+): string | null {
+	const slice = userVisiblePromptSlice(prompt);
+	for (const line of slice.split("\n")) {
+		const trimmed = line.trim();
+		const parsed = parseHarnessSlashInput(trimmed);
+		if (parsed) return trimmed;
+	}
+	if (entries?.length) {
+		const turn = getLatestHarnessTurn(entries);
+		if (turn?.command) {
+			return `/${turn.command}${turn.args ? ` ${turn.args}` : ""}`.trim();
+		}
+	}
+	return null;
 }
 
 /** Mirrors policy-gate phase checks so run-context does not inject on blocked turns. */
@@ -2007,20 +2124,6 @@ export function isNewTaskPlanBlocked(
 	return newTask.length > 0 && prior.length > 0;
 }
 
-export type RemediationClass =
-	| "pass"
-	| "implementation_gap"
-	| "plan_gap"
-	| "rollback"
-	| "inconclusive";
-
-export interface ReviewOutcomeLike {
-	schema_version?: string;
-	status?: string;
-	remediation_class?: RemediationClass | string;
-	recommended_next?: string;
-}
-
 export async function readReviewOutcomeFromRun(
 	runId: string,
 	projectRoot: string,
@@ -2038,62 +2141,6 @@ export async function readReviewOutcomeFromRun(
 	}
 }
 
-/** Infer remediation when parent skipped Phase 6 but eval-verdict exists on disk. */
-export function remediationClassFromEvalVerdict(
-	verdict: EvalVerdictDisk | null,
-): RemediationClass | null {
-	if (!verdict) return null;
-	const status = (verdict.status ?? "").toLowerCase();
-	if (status === "pass") return "pass";
-	const action = (verdict.recommended_action ?? "").toLowerCase();
-	if (
-		action === "replan" ||
-		action.includes("revise") ||
-		action.includes("plan")
-	) {
-		return "plan_gap";
-	}
-	if (action === "rollback" || action.includes("rollback")) {
-		return "rollback";
-	}
-	if (
-		action === "steer" ||
-		action === "repair" ||
-		action.includes("implement")
-	) {
-		return "implementation_gap";
-	}
-	const failed = (verdict as EvalVerdictDisk & { failed_checks?: string[] })
-		.failed_checks;
-	const joined = Array.isArray(failed) ? failed.join(" ").toLowerCase() : "";
-	if (
-		joined.includes("scope_minimization") ||
-		joined.includes("scope_drift") ||
-		joined.includes("replan")
-	) {
-		return "plan_gap";
-	}
-	if (status === "fail") return "inconclusive";
-	return null;
-}
-
-export function recommendedNextForRemediation(
-	remediation: RemediationClass,
-): string {
-	switch (remediation) {
-		case "pass":
-			return "/harness-policy-status";
-		case "implementation_gap":
-			return "/harness-steer";
-		case "plan_gap":
-			return "/harness-plan (mode: revise)";
-		case "rollback":
-			return "/harness-incident";
-		default:
-			return "/harness-review";
-	}
-}
-
 export async function resolveRemediationClassForRun(
 	runId: string,
 	projectRoot: string,

package/.pi/lib/harness-spawn-budget.ts

@@ -1,8 +1,23 @@
 /**
  * Harness subagent spawn accounting (subprocess model).
- * No session caps — parallel batches are limited only by host resources.
+ * When HARNESS_BUDGET_ENFORCE=1, per-phase spawn caps apply.
  */
 
+import { isHarnessBudgetEnforceOn } from "./harness-budget-enforce.js";
+import type { HarnessPhase } from "./harness-run-context.js";
+
+const PHASE_SPAWN_CAPS: Record<HarnessPhase, number> = {
+	plan: 12,
+	execute: 3,
+	evaluate: 6,
+	adversary: 4,
+	merge: 2,
+};
+
+export function phaseSpawnCap(phase: HarnessPhase): number {
+	return PHASE_SPAWN_CAPS[phase];
+}
+
 export function isHarnessAgentType(type: string): boolean {
 	return type.startsWith("harness/");
 }
@@ -31,11 +46,24 @@ export function countHarnessAgentsInRequest(params: {
 	return { harnessCount: harness.length, agents: harness };
 }
 
-/** Always allows spawn; state is tracked for telemetry only. */
 export function checkHarnessSpawnBudget(
-	_state: SpawnBudgetState,
-	_incomingHarnessTasks: number,
+	state: SpawnBudgetState,
+	incomingHarnessTasks: number,
+	phase?: HarnessPhase,
 ): { ok: boolean; message?: string } {
+	if (!isHarnessBudgetEnforceOn() || !phase) {
+		return { ok: true };
+	}
+	const cap = PHASE_SPAWN_CAPS[phase];
+	const projected = state.totalHarnessSpawns + incomingHarnessTasks;
+	if (projected > cap) {
+		return {
+			ok: false,
+			message:
+				`Spawn budget exceeded for ${phase} phase (${projected}/${cap}). ` +
+				`Use harness_plan_next_action or reduce spawns; set HARNESS_BUDGET_ENFORCE=0 to disable.`,
+		};
+	}
 	return { ok: true };
 }
 

package/.pi/lib/harness-spawn-topology.ts

@@ -7,6 +7,11 @@ import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { validateHarnessArtifactFile } from "./harness-artifact-gate.js";
+import {
+	synthesizerAllowsRespawn,
+	synthesizerArtifactsComplete,
+} from "./harness-plan-route.js";
+import { isHarnessReviewParallelEnabled } from "./harness-review-parallel.js";
 import type { HarnessPhase } from "./harness-run-context.js";
 import { validateTaskClarificationReadyWithHumanGate } from "./plan-human-gates.js";
 
@@ -17,6 +22,7 @@ export interface SpawnTopologyResult {
 
 const DECOMPOSE_AGENT = "harness/planning/decompose";
 const HYPOTHESIS_AGENT = "harness/planning/hypothesis";
+const SYNTHESIZER_AGENT = "harness/planning/plan-synthesizer";
 
 const DEBATE_LANE_AGENTS = new Set([
 	"harness/planning/hypothesis-validator",
@@ -124,7 +130,7 @@ function validateParallelBatch(
 	const reviewEvaluator = "harness/reviewing/evaluator";
 	const reviewAdversary = "harness/reviewing/adversary";
 	const reviewParallelPair =
-		process.env.HARNESS_REVIEW_PARALLEL === "1" &&
+		isHarnessReviewParallelEnabled() &&
 		names.includes(reviewEvaluator) &&
 		names.includes(reviewAdversary) &&
 		names.filter((n) => n === reviewEvaluator || n === reviewAdversary)
@@ -199,6 +205,10 @@ async function validateHypothesisDependency(
 	if (!(names.includes(HYPOTHESIS_AGENT) && opts?.projectRoot && opts?.runId)) {
 		return null;
 	}
+	const runRoot = join(opts.projectRoot, ".pi", "harness", "runs", opts.runId);
+	if (await synthesizerArtifactsComplete(runRoot)) {
+		return "Synthesizer path complete — spawn execution-plan-author instead of hypothesis.";
+	}
 	const ready = await decompositionReady(opts.projectRoot, opts.runId);
 	if (ready) return null;
 	return (
@@ -207,6 +217,21 @@ async function validateHypothesisDependency(
 	);
 }
 
+async function validateSequentialPathBlocks(
+	names: string[],
+	opts?: { projectRoot?: string; runId?: string | null },
+): Promise<string | null> {
+	if (!(opts?.projectRoot && opts?.runId)) return null;
+	const runRoot = join(opts.projectRoot, ".pi", "harness", "runs", opts.runId);
+	if (
+		(names.includes(DECOMPOSE_AGENT) || names.includes(HYPOTHESIS_AGENT)) &&
+		(await synthesizerArtifactsComplete(runRoot))
+	) {
+		return "Synthesizer path artifacts present — use execution-plan-author, not decompose/hypothesis.";
+	}
+	return null;
+}
+
 function validatePlanPhaseMutations(
 	names: string[],
 	phase: HarnessPhase,
@@ -258,6 +283,13 @@ async function validateArtifactCompletionDedup(
 	const specsDir = join(opts.projectRoot, ".pi", "harness", "specs");
 
 	for (const name of names) {
+		if (name === SYNTHESIZER_AGENT) {
+			if (await synthesizerAllowsRespawn(runRoot)) continue;
+			return (
+				`Duplicate spawn blocked: ${name} already produced synthesizer artifacts. ` +
+				`Advance to execution-plan-author or set HARNESS_FORCE_RESPAWN=1.`
+			);
+		}
 		const artifactRel = PLANNING_AGENT_ARTIFACT[name];
 		if (!artifactRel) continue;
 		if (await artifactAllowsRespawn(runRoot, artifactRel)) continue;
@@ -299,6 +331,9 @@ export async function validateHarnessSpawnTopology(
 	const parallelError = validateParallelBatch(names, taskCount);
 	if (parallelError) return { ok: false, message: parallelError };
 
+	const sequentialBlock = await validateSequentialPathBlocks(names, opts);
+	if (sequentialBlock) return { ok: false, message: sequentialBlock };
+
 	const hypothesisError = await validateHypothesisDependency(names, opts);
 	if (hypothesisError) return { ok: false, message: hypothesisError };
 

package/.pi/lib/harness-subagent-precheck.ts

@@ -8,6 +8,7 @@ import {
 } from "../../vendor/pi-subagents/src/agents.js";
 import { getAgentKind } from "./agents-policy.mjs";
 import { getHarnessPackageRoot } from "./harness-paths.js";
+import { isHarnessReviewParallelEnabled } from "./harness-review-parallel.js";
 import { type HarnessPhase, inferHarnessPhase } from "./harness-run-context.js";
 import { validateHarnessSpawnTopology } from "./harness-spawn-topology.js";
 import { shouldBlockSubagentForMissingPlanApproval } from "./plan-human-gates.js";
@@ -103,15 +104,15 @@ export async function precheckHarnessSubagentSpawn(
 		};
 	}
 
+	const steerAttempt = parseSteerAttemptFromTasks(params);
 	const parallelEvalAdversary =
-		process.env.HARNESS_REVIEW_PARALLEL === "1" &&
+		isHarnessReviewParallelEnabled({ quick: opts?.quick, steerAttempt }) &&
 		(params.tasks?.length ?? 0) === 2 &&
 		params.tasks?.some((t) => t.agent === "harness/reviewing/evaluator") &&
 		params.tasks?.some((t) => t.agent === "harness/reviewing/adversary") &&
 		names.length === 2 &&
 		phase === "evaluate";
 
-	const steerAttempt = parseSteerAttemptFromTasks(params);
 	if (
 		steerAttempt >= 2 &&
 		names.includes("harness/reviewing/adversary") &&

package/.pi/lib/harness-subagent-progress.ts

@@ -1,5 +1,5 @@
 /**
- * In-process progress state for harness live widget + stderr heartbeat.
+ * In-process progress state for the harness live widget (no stderr output).
  */
 
 export type HarnessWaitGate = "ask_user" | "approve_plan" | null;
@@ -86,23 +86,26 @@ export function buildHarnessProgressStatusLine(): string | null {
 		const agents = snapshot.activeSubagentAgents
 			.map((a) => a.replace(/^harness\//, ""))
 			.join(", ");
+		const agentsLabel = agents.length > 36 ? `${agents.slice(0, 33)}…` : agents;
 		const phase = snapshot.harnessPhase ?? "harness";
-		return `${phase} · ${agents} · ${elapsed}`;
+		return `${phase} · ${agentsLabel} · ${elapsed}`;
 	}
 	return null;
 }
 
 export function startHarnessSubagentHeartbeat(
 	onTick: (line: string) => void,
-	intervalMs = 30_000,
+	intervalMs = 10_000,
 ): void {
 	stopHarnessSubagentHeartbeat();
-	heartbeatTimer = setInterval(() => {
+	const tick = (): void => {
 		const line = buildHarnessProgressStatusLine();
 		if (!line) return;
 		snapshot = { ...snapshot, lastHeartbeatLine: line };
 		onTick(line);
-	}, intervalMs);
+	};
+	tick();
+	heartbeatTimer = setInterval(tick, intervalMs);
 	if (typeof heartbeatTimer.unref === "function") {
 		heartbeatTimer.unref();
 	}

package/.pi/lib/harness-subagents-bridge.ts

@@ -24,6 +24,7 @@ import {
 	incrementHarnessPhaseSubagentCount,
 	recordHarnessPhaseStart,
 } from "./harness-phase-telemetry.js";
+import { isHarnessPhaseWorkerEnabled } from "./harness-phase-worker.js";
 import { captureHarnessEvent } from "./harness-posthog.js";
 import {
 	getLatestRunContext,
@@ -48,7 +49,6 @@ import {
 	precheckHarnessSubagentSpawn,
 } from "./harness-subagent-precheck.js";
 import {
-	buildHarnessProgressStatusLine,
 	clearHarnessSubagentProgress,
 	setHarnessSubagentProgress,
 	startHarnessSubagentHeartbeat,
@@ -154,6 +154,9 @@ export function createHarnessSubagentsExtension(
 				HARNESS_PKG_ROOT: packageRoot,
 				HARNESS_PROJECT_ROOT: projectRoot,
 			};
+			if (isHarnessPhaseWorkerEnabled()) {
+				base.HARNESS_PHASE_WORKER = "1";
+			}
 			if (agent.name.startsWith("harness/web-retrieval/")) {
 				const ctx = parseSpawnContextFromTask(task);
 				const remembered = getRememberedSessionWebArtifactDir(lastSessionId);
@@ -223,13 +226,17 @@ export function createHarnessSubagentsExtension(
 			);
 			pendingSpawnTelemetry = null;
 			if (harnessCount > 0) {
-				const budget = checkHarnessSpawnBudget(spawnBudget, harnessCount);
+				const entries = ctx.sessionManager.getEntries();
+				const phase = inferPhaseForPrecheck(entries);
+				const budget = checkHarnessSpawnBudget(
+					spawnBudget,
+					harnessCount,
+					phase,
+				);
 				if (!budget.ok) {
 					return { ok: false, message: budget.message };
 				}
-				const entries = ctx.sessionManager.getEntries();
 				const runCtx = getLatestRunContext(entries);
-				const phase = inferPhaseForPrecheck(entries);
 				const pre = await precheckHarnessSubagentSpawn(
 					params as Parameters<typeof precheckHarnessSubagentSpawn>[0],
 					agents,
@@ -303,9 +310,8 @@ export function createHarnessSubagentsExtension(
 				agent_ids: agentIds,
 				agent_count: agentIds.length,
 			});
-			startHarnessSubagentHeartbeat((line) => {
-				console.error(`harness-progress: ${line}`);
-				bridgePi?.events.emit("harness-progress:updated", { line });
+			startHarnessSubagentHeartbeat(() => {
+				bridgePi?.events.emit("harness-progress:updated", {});
 			});
 			captureHarnessEvent(lastSessionId, "harness_subagent_spawned", {
 				active_after: spawnBudget.active,
@@ -328,12 +334,8 @@ export function createHarnessSubagentsExtension(
 		},
 		onCompleted: ({ agents, mode, durationMs, timedOut, stop_reason }) => {
 			stopHarnessSubagentHeartbeat();
-			const statusLine = buildHarnessProgressStatusLine();
-			if (statusLine) {
-				console.error(`harness-progress: ${statusLine} (done)`);
-			}
 			clearHarnessSubagentProgress();
-			bridgePi?.events.emit("harness-progress:updated", { line: null });
+			bridgePi?.events.emit("harness-progress:updated", {});
 
 			if (agents.length === 0) return;
 			const runId = pendingSpawnTelemetry?.run_id ?? lastSessionId;

package/.pi/lib/harness-vcc-settings.ts

@@ -10,6 +10,14 @@ export interface PiVccSettings {
 	overrideDefaultCompaction: boolean;
 	/** Write debug snapshot to /tmp/pi-vcc-debug.json on each compaction. */
 	debug: boolean;
+	/** Compact when context usage ≥ this percent (harness auto-compact extension). */
+	compactThresholdPercent: number;
+	/** Hysteresis: re-arm after usage falls below this percent. */
+	compactRearmPercent: number;
+	/** Enable harness 50% auto-compact gate. */
+	compactAuto: boolean;
+	/** Allow auto-compact in subagent subprocesses (default false). */
+	compactSubagents: boolean;
 }
 
 const FALSE_VALUES = new Set(["false", "0", "off", "no"]);
@@ -39,10 +47,38 @@ export function resolveVccDebug(): boolean {
 	return parseHarnessBool("HARNESS_VCC_DEBUG", false);
 }
 
+function parseHarnessPercent(envName: string, defaultValue: number): number {
+	const raw = process.env[envName]?.trim();
+	if (!raw) return defaultValue;
+	const n = Number.parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 1 || n > 99) return defaultValue;
+	return n;
+}
+
+export function resolveCompactThresholdPercent(): number {
+	return parseHarnessPercent("HARNESS_COMPACT_THRESHOLD_PERCENT", 50);
+}
+
+export function resolveCompactRearmPercent(): number {
+	return parseHarnessPercent("HARNESS_COMPACT_REARM_PERCENT", 40);
+}
+
+export function resolveCompactAuto(): boolean {
+	return parseHarnessBool("HARNESS_COMPACT_AUTO", true);
+}
+
+export function resolveCompactSubagents(): boolean {
+	return parseHarnessBool("HARNESS_COMPACT_SUBAGENTS", false);
+}
+
 export function loadSettings(): PiVccSettings {
 	return {
 		overrideDefaultCompaction: resolveOverrideDefaultCompaction(),
 		debug: resolveVccDebug(),
+		compactThresholdPercent: resolveCompactThresholdPercent(),
+		compactRearmPercent: resolveCompactRearmPercent(),
+		compactAuto: resolveCompactAuto(),
+		compactSubagents: resolveCompactSubagents(),
 	};
 }