ultimate-pi 0.23.0 → 0.25.0

package/.pi/lib/plan-human-gates.ts

@@ -9,15 +9,22 @@ import {
 	isHarnessNonInteractive,
 	isPlanApprovalAskUser,
 } from "./ask-user/policy.js";
+import {
+	isHarnessPlanAutoApproveEnabled,
+} from "./harness-auto-approve.js";
 import {
 	hasPlanUserApproval,
 	indexOfLastPlanCommand,
 } from "./harness-run-context.js";
 import { validatePlanApprovalReadiness } from "./plan-approval-readiness.js";
+import { loadPlanDebateEligibilitySnapshot } from "./plan-debate-eligibility-snapshot.js";
 import {
 	buildPlanDebateGateRecovery,
 	validatePlanDebateGate,
 } from "./plan-debate-gate.js";
+
+export { canAutoApprovePlan } from "./harness-auto-approve.js";
+
 import {
 	isTaskClarificationReady,
 	readTaskClarificationDoc,
@@ -28,32 +35,8 @@ import {
 const EXPLICIT_ACCEPTANCE_RE =
 	/\b(acceptance|success criteria|definition of done|done when|must (pass|satisfy)|out of scope|in scope)\b/i;
 
-function logPlanHumanGate(payload: {
-	runId: string;
-	hypothesisId: string;
-	location: string;
-	message: string;
-	data: Record<string, unknown>;
-}): void {
-	// #region agent log
-	fetch("http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0", {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			"X-Debug-Session-Id": "f7763e",
-		},
-		body: JSON.stringify({
-			sessionId: "f7763e",
-			runId: payload.runId,
-			hypothesisId: payload.hypothesisId,
-			location: payload.location,
-			message: payload.message,
-			data: payload.data,
-			timestamp: Date.now(),
-		}),
-	}).catch(() => {});
-	// #endregion
-}
+const QA_SMOKE_TASK_RE =
+	/\b(qa smoke|e2e-last-run|evals\/smoke\/|iso-?8601.*timestamp|append one .* timestamp line)\b/i;
 
 type SessionEntryLike = {
 	type?: string;
@@ -87,7 +70,6 @@ function askUserCallWasTaskClarification(details: unknown): boolean {
 export function hasTaskClarificationAskUserSincePlanCommand(
 	entries: unknown[],
 ): boolean {
-	if (isNonInteractivePlan()) return true;
 	const since = Math.max(0, indexOfLastPlanCommand(entries));
 	for (let i = since; i < entries.length; i++) {
 		const entry = entries[i] as SessionEntryLike;
@@ -138,6 +120,7 @@ export function hasClarificationFollowUpUserMessage(
 export function isExplicitTaskAcceptance(taskSummary: string): boolean {
 	const t = taskSummary.trim();
 	if (t.length < 24) return false;
+	if (QA_SMOKE_TASK_RE.test(t)) return true;
 	return EXPLICIT_ACCEPTANCE_RE.test(t);
 }
 
@@ -166,6 +149,14 @@ export function validateTaskClarificationHumanGate(
 		return { ok: true, errors };
 	}
 
+	if (process.env.HARNESS_PLAN_NONINTERACTIVE === "1") {
+		return { ok: true, errors };
+	}
+
+	if (isHarnessPlanAutoApproveEnabled() && isHarnessNonInteractive()) {
+		return { ok: true, errors };
+	}
+
 	if (hasTaskClarificationAskUserSincePlanCommand(entries)) {
 		return { ok: true, errors };
 	}
@@ -217,51 +208,11 @@ export async function resolvePlanHumanGateStatus(
 	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
 	const clar = await isTaskClarificationReady(runDir);
 	const clarDoc = clar.ok ? await readTaskClarificationDoc(runDir) : null;
-	logPlanHumanGate({
-		runId,
-		hypothesisId: "H3",
-		location: "plan-human-gates.ts:resolvePlanHumanGateStatus:clar",
-		message: "Task clarification readiness evaluated",
-		data: {
-			runDir,
-			clarOk: clar.ok,
-			clarErrors: clar.errors,
-			docStatus: String(clarDoc?.status ?? ""),
-			docEngagementSource:
-				typeof clarDoc?.user_engagement === "object" &&
-				clarDoc?.user_engagement !== null
-					? String(
-							(
-								clarDoc.user_engagement as {
-									source?: string;
-								}
-							).source ?? "",
-						)
-					: "",
-		},
-	});
 	const humanGate = validateTaskClarificationHumanGate(entries, clarDoc, {
 		quick: opts?.quick,
 		taskSummary: opts?.taskSummary,
 		allowFollowUpMessage: opts?.lastOutcome === "needs_clarification",
 	});
-	logPlanHumanGate({
-		runId,
-		hypothesisId: "H1-H2",
-		location: "plan-human-gates.ts:resolvePlanHumanGateStatus:humanGate",
-		message: "Human gate evaluated for phase0 ask_user requirement",
-		data: {
-			humanGateOk: humanGate.ok,
-			humanGateErrors: humanGate.errors,
-			allowFollowUpMessage: opts?.lastOutcome === "needs_clarification",
-			hasTaskClarificationAskUserSincePlanCommand:
-				hasTaskClarificationAskUserSincePlanCommand(entries),
-			hasClarificationFollowUpUserMessage:
-				hasClarificationFollowUpUserMessage(entries),
-			indexOfLastPlanCommand: indexOfLastPlanCommand(entries),
-			entriesLen: entries.length,
-		},
-	});
 	const phase0Ready = clar.ok && humanGate.ok;
 	const phase0NeedsAskUser = clar.ok && !humanGate.ok;
 	const approvalRecorded = hasPlanUserApproval(entries, {
@@ -274,7 +225,6 @@ export async function resolvePlanHumanGateStatus(
 
 	let debateComplete = true;
 	let debateGate = null;
-	let readinessOk = false;
 	let approvalRequired = false;
 
 	if (phase0Ready && !approvalRecorded) {
@@ -282,8 +232,12 @@ export async function resolvePlanHumanGateStatus(
 			risk_level: String(clarDoc?.risk_level ?? "med"),
 			quick: opts?.quick,
 		});
-		readinessOk = readiness.ok;
-		debateGate = await validatePlanDebateGate(projectRoot, runId);
+		const eligibility = await loadPlanDebateEligibilitySnapshot(runDir);
+		debateGate = await validatePlanDebateGate(
+			projectRoot,
+			runId,
+			eligibility ?? undefined,
+		);
 		debateComplete = debateGate.ok;
 		approvalRequired = readiness.ok && debateComplete && hasPacket;
 	}
@@ -311,21 +265,6 @@ export async function resolvePlanHumanGateStatus(
 	} else if (approvalRequired && !approvalRecorded) {
 		nextRequiredAction = "approve_plan then create_plan (Phase 6)";
 	}
-	logPlanHumanGate({
-		runId,
-		hypothesisId: "H4",
-		location: "plan-human-gates.ts:resolvePlanHumanGateStatus:result",
-		message: "Resolved plan human gate status",
-		data: {
-			phase0Ready,
-			phase0NeedsAskUser,
-			debateComplete,
-			debateRequired,
-			approvalRequired,
-			approvalRecorded,
-			nextRequiredAction,
-		},
-	});
 
 	return {
 		phase0Ready,

package/.pi/lib/plan-messenger.ts

@@ -63,8 +63,8 @@ export interface MessengerState {
 	rounds: Record<string, MessengerRoundState>;
 	debate_profile?: DebateProfile;
 	required_focuses?: PlanDebateFocus[];
-	/** consolidated = single Review Gate round; threaded = per-focus rounds */
-	review_gate_mode?: "consolidated" | "threaded";
+	/** consolidated | parallel_probes = single round; threaded = per-focus rounds */
+	review_gate_mode?: "consolidated" | "threaded" | "parallel_probes";
 }
 
 function messengerRoot(runDir: string): string {
@@ -86,7 +86,7 @@ export async function initPlanMessenger(
 		debateId: string;
 		debate_profile?: DebateProfile;
 		required_focuses?: PlanDebateFocus[];
-		review_gate_mode?: "consolidated" | "threaded";
+		review_gate_mode?: "consolidated" | "threaded" | "parallel_probes";
 	},
 ): Promise<string> {
 	const root = messengerRoot(runDir);

package/.pi/lib/plan-review-gate.ts

@@ -2,13 +2,17 @@
  * Consolidated vs threaded Review Gate strategy for plan-phase debate.
  */
 
+import type { capsForDebate } from "./debate-bus-core.js";
 import type {
 	DebateEligibilityResult,
+	DebateProfile,
 	PlanReviewGateStrategy,
 } from "./plan-debate-eligibility.js";
 import type { PlanDebateFocus } from "./plan-debate-focus.js";
+import type { MessengerState } from "./plan-messenger.js";
 
 export type { PlanReviewGateStrategy };
+export type ReviewGateMode = PlanReviewGateStrategy["mode"];
 
 export const CONSOLIDATED_REVIEW_ROUND = 1;
 export const CONSOLIDATED_REVIEW_ARTIFACT =
@@ -57,3 +61,55 @@ export function consolidatedReviewFocusesSatisfied(
 ): boolean {
 	return CONSOLIDATED_REVIEW_FOCUS_AREAS.every((f) => covered.includes(f));
 }
+
+/** Single SSOT: profile → messenger review_gate_mode. */
+export function planReviewGateModeForProfile(
+	profile: DebateProfile,
+): ReviewGateMode {
+	if (profile === "fast") return "consolidated";
+	if (profile === "standard") return "parallel_probes";
+	return "threaded";
+}
+
+/** parallel_probes and consolidated submit one round — cap min_focus_rounds. */
+export function effectiveMinFocusRounds(
+	strategy: PlanReviewGateStrategy,
+): number {
+	if (strategy.mode === "parallel_probes" || strategy.mode === "consolidated") {
+		return 1;
+	}
+	return strategy.min_focus_rounds;
+}
+
+export function reviewStrategyFromMessenger(
+	messenger: MessengerState,
+	profile: DebateProfile,
+	requiredFocuses: readonly PlanDebateFocus[],
+	caps: ReturnType<typeof capsForDebate>,
+): PlanReviewGateStrategy {
+	const mode =
+		messenger.review_gate_mode ?? planReviewGateModeForProfile(profile);
+	return {
+		mode,
+		profile,
+		required_focuses: [...requiredFocuses],
+		min_focus_rounds: effectiveMinFocusRounds({
+			mode,
+			profile,
+			required_focuses: [...requiredFocuses],
+			min_focus_rounds: caps.min_focus_rounds,
+			max_rounds: caps.max_rounds,
+			max_exchanges_per_round: caps.max_exchanges_per_round,
+			round_token_cap: caps.round_token_cap,
+			debate_global_cap: caps.debate_global_cap,
+			rationale: [],
+		}),
+		max_rounds: caps.max_rounds,
+		max_exchanges_per_round: caps.max_exchanges_per_round,
+		round_token_cap: caps.round_token_cap,
+		debate_global_cap: caps.debate_global_cap,
+		rationale: messenger.review_gate_mode
+			? [`messenger review_gate_mode=${messenger.review_gate_mode}`]
+			: [],
+	};
+}

package/.pi/prompts/harness-abort.md

@@ -15,6 +15,7 @@ Safely abort the current harness run in this session.
   - `planId: null`
 - clears active run `plan_ready` (plan files may remain on disk for forensics)
 - records abort metadata for observability
+- returns immediately without continuing work under the previous run
 - enables a hard safety lock that blocks mutating tools until a new approved plan is attached
 
 ## Usage

package/.pi/prompts/harness-auto.md

@@ -20,7 +20,7 @@ If task missing:
 
 Follow **harness-plan** performance rules (`subagent` with `agentScope: "both"`). Use parallel `tasks` only for Phase 3.5 research (≤2 lanes) when subprocesses are needed. Never parallelize decompose∥hypothesis or debate lanes — precheck enforces this.
 
-1. **Plan** — follow `/harness-plan` (task clarification gate → context → lakes/synthesis or sequential framing → research → plan-verify → `approve_plan()` + `create_plan()`). One approval.
+1. **Plan** — follow `/harness-plan`; drive steps via `harness_plan_next_action`. When `HARNESS_PLAN_AUTO_APPROVE=1` and deterministic gates pass (non-interactive), `approve_plan` auto-approves. Otherwise one human approval.
 2. **Execute** — `harness/running/executor` with `executor_strategy` from packet (default `single_pass` for low/med).
 3. **Review** — always **`/harness-review`** after execute (no benchmark fail-fast).
 4. **Steer loop** — while `review-outcome.remediation_class === implementation_gap` and `steer_attempt < HARNESS_STEER_MAX_ATTEMPTS`: `/harness-steer` → `/harness-review` (tiered adversary on attempts 2+).

package/.pi/prompts/harness-clear.md

@@ -1,18 +1,18 @@
 ---
-description: Safely delete historical harness run directories while preserving the active run.
+description: Safely delete all harness run directories, including the active run.
 ---
 
 # harness-clear
 
-Delete only historical run directories under `.pi/harness/runs/`.
+Delete all run directories under `.pi/harness/runs/`, including the current active run.
 
 ## What this does
 
 - enumerates delete candidates strictly from `.pi/harness/runs/<run_id>/`
-- always preserves active run ids discovered from session context and active-run pointer
+- includes active run ids discovered from session context and the active-run pointer
 - asks for one confirmation before any filesystem mutation
 - fails closed: cancel/decline/timeout/error/unavailable confirmation paths delete nothing
-- reports deleted vs protected/skipped counts
+- clears `.pi/harness/active-run.json` and reports deleted vs skipped counts
 
 ## Usage
 
@@ -20,6 +20,6 @@ Delete only historical run directories under `.pi/harness/runs/`.
 
 ## Safety boundaries
 
-- in scope: historical run directories only
-- out of scope: full `.pi/harness/` reset, non-run harness assets, active-run deletion overrides
+- in scope: all run directories plus `.pi/harness/active-run.json`
+- out of scope: full `.pi/harness/` reset and non-run harness assets
 - confirmation is mandatory; non-affirmative outcomes are no-op

package/.pi/prompts/harness-plan.md

@@ -7,6 +7,8 @@ argument-hint: "\"<task>\" [--risk low|med|high] [--quick]"
 
 You are the **planning orchestrator**. Produce an execution baseline (`plan-packet.yaml` + `plan-review.md`) with **lake-sized** outcomes and path-first tools. Parent owns gates: `ask_user`, `approve_plan({ human_summary? })`, `create_plan()`, plan-verify, and scoped writes under `.pi/harness/runs/<run_id>/`.
 
+**Happy path:** call `harness_plan_next_action` → execute the returned spawn/tool/gate → `harness_artifact_ready` → repeat. Use `harness_plan_route` for synthesizer vs sequential framing. Context compacts automatically at 50% usage (VCC); call `vcc_recall` if task state is unclear after compaction.
+
 Use the phase order and spawn topology defined in this prompt directly.
 
 Subagents persist artifacts via scoped **`submit_*`** tools (deterministic YAML under the run dir). Parent uses **`harness_artifact_ready`** to gate phases (no JSON parsing). Parent merges still use **`write_harness_yaml`** for `research-brief.yaml`, `plan-packet.yaml`, `planning-context.yaml`, and integrator patches.
@@ -270,7 +272,7 @@ Med/low non-fork plans with clear stack and no implementation `open_questions` d
 
 **Practice:** Code Complete collaborative construction with Fagan-style inspection criteria. Parent is **chair**; one debate agent per `subagent` batch.
 
-**Forbidden:** parallel `subagent` calls for any debate lane agent in one batch.
+**Forbidden:** parallel debate lanes except **plan-evaluator ∥ plan-adversary** when `review_gate_mode: parallel_probes` (med default).
 
 1. Optional: `harness_plan_scope_check` — if `material_drift`, `ask_user` before debate.
 2. Drive debate with **`harness_debate_focus_coverage`** and **`harness_debate_round_status({ round_index, debate_round_focus })`** — cover **required_focuses** from eligibility, not always all four.
@@ -296,7 +298,18 @@ IF review_gate_ready false OR blockers: escalate — threaded round per missing
 harness_debate_focus_coverage → harness_debate_consensus
 ```
 
-### Threaded state machine (standard/full/light)
+### Parallel probes state machine (`review_gate_mode: parallel_probes`, profile standard)
+
+```
+round_index := 1
+debate_round_focus := all
+spawn hypothesis-validator (blind verifier)
+spawn parallel batch: plan-evaluator ∥ plan-adversary
+spawn review-integrator → harness_debate_submit_round (review-round-parallel-probes.yaml)
+harness_debate_focus_coverage → harness_debate_consensus
+```
+
+### Threaded state machine (full/light)
 
 ```
 round_index := next uncovered required focus

package/.pi/prompts/harness-review.md

@@ -21,10 +21,12 @@ Read **harness-orchestration** and **harness-review** skills before spawning.
 ## Performance rules
 
 1. Use `subagent` with `agentScope: "both"`.
-2. Run benchmark and verdict evaluator passes **sequentially** (verdict depends on benchmark gate).
-3. Adversary runs only after benchmark + policy verdict pass.
-4. Do **not** set `timeoutMs` unless the user requests a cap.
-5. Compact task text: embed `HarnessSpawnContext={"run_id":"…","run_dir":"…","plan_packet_path":"…",…}` — `run_id` is required.
+2. Run benchmark and verdict evaluator passes **sequentially** (verdict depends on benchmark gate). **Never** parallelize benchmark ∥ verdict.
+3. When benchmark passed (and not `--quick`, steer attempt < 2), spawn **verdict evaluator ∥ adversary** in one `tasks` batch by default. Set `HARNESS_REVIEW_PARALLEL=0` to force serial. While benchmark runs, prepare adversary context but do not spawn adversary until benchmark passes.
+4. Adversary runs only after benchmark passes; skip adversary when benchmark failed or `--quick`.
+5. Steer attempts **2+**: lite review (benchmark + verdict only) unless prior `block_merge` — do not spawn adversary.
+6. Do **not** set `timeoutMs` unless the user requests a cap (harness applies phase-aware defaults).
+7. Compact task text: embed `HarnessSpawnContext={"run_id":"…","run_dir":"…","plan_packet_path":"…",…}` — `run_id` is required.
 
 ## Step 0 — Parse `$ARGUMENTS`
 
@@ -135,11 +137,27 @@ harness_artifact_ready({ paths: ["artifacts/eval-verdict.yaml"] })
 
 **Do not stop** after benchmark fail — continue to verdict (and adversary per tier) so `review-outcome.yaml` can route steer vs replan.
 
-## Phase 3 — Policy / quality audit (verdict evaluator)
+## Phase 3–4 — Verdict + adversary (serial or parallel)
 
 **Practice:** Inspection after measurement — separate measurer from policy judgment.
 
-Always run after benchmark (even when benchmark failed).
+Always run verdict after benchmark (even when benchmark failed).
+
+**Serial (default):** spawn verdict evaluator, gate `eval-verdict.yaml`, then spawn adversary (unless `--quick` or steer attempt ≥ 2 without prior `block_merge`).
+
+**Parallel (default):** when benchmark passed, not `--quick`, steer attempt < 2 (or prior `block_merge`), unless `HARNESS_REVIEW_PARALLEL=0`:
+
+```
+subagent({
+  agentScope: "both",
+  tasks: [
+    { agent: "harness/reviewing/evaluator", task: "<HarnessSpawnContext mode verdict + …>" },
+    { agent: "harness/reviewing/adversary", task: "<HarnessSpawnContext mode adversary + …>" }
+  ]
+})
+```
+
+**Serial fallback:**
 
 ```
 subagent({
@@ -151,13 +169,9 @@ subagent({
 
 Subagent updates **`artifacts/eval-verdict.yaml`** via `submit_eval_verdict` (include policy fields / failed checks).
 
-Gate again with `harness_artifact_ready`.
-
-## Phase 4 — Independent red team (adversary)
-
-**Practice:** Generator–evaluator separation; adversary stays distinct from the measurer.
+Gate with `harness_artifact_ready({ paths: ["artifacts/eval-verdict.yaml"] })`.
 
-Skip when `--quick`. **Tiered steer:** full adversary on initial run + steer attempt 1; lite review (no adversary) on steer attempts 2+ unless prior `block_merge`.
+**Adversary** (Phase 4): skip when `--quick`. **Tiered steer:** full adversary on initial run + steer attempt 1; lite review on steer attempts 2+ unless prior `block_merge`.
 
 ```
 subagent({

package/.pi/scripts/harness-e2e-workflow.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Manual terminal E2E for harness plan → run → review latency fixes.
+ * ADR 0004: not part of default CI — run with --e2e-live or directly.
+ *
+ * Usage:
+ *   node .pi/scripts/harness-e2e-workflow.mjs [--quick] [--task "…"]
+ *
+ * Requires: pi on PATH, HARNESS_ASK_USER_UI=headless (set by this script).
+ * Does NOT use `pi -p` for the main workflow (Phase 0 ask_user blocks -p).
+ */
+
+import { spawn } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const pkgRoot = process.cwd();
+const sessionId = `harness-latency-e2e-${Date.now()}`;
+const logDir = join(pkgRoot, ".pi", "harness", "runs");
+const logPath = join(logDir, `_e2e-latency-fixes-${sessionId}.log`);
+
+const args = process.argv.slice(2);
+const quick = args.includes("--quick");
+const taskIdx = args.indexOf("--task");
+const task =
+	taskIdx >= 0 && args[taskIdx + 1]
+		? args[taskIdx + 1]
+		: 'smoke: append one line to .pi/harness/evals/smoke/E2E-LAST-RUN.txt with ISO timestamp and run_id; no other files; unit test only';
+
+async function run(cmd, cmdArgs, env = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(cmd, cmdArgs, {
+			cwd: pkgRoot,
+			env: { ...process.env, ...env },
+			stdio: "inherit",
+		});
+		child.on("error", reject);
+		child.on("close", (code) => resolve(code ?? 1));
+	});
+}
+
+async function main() {
+	await mkdir(logDir, { recursive: true });
+	console.error(`harness-e2e: log ${logPath}`);
+
+	const verifyCode = await run("node", [join(pkgRoot, ".pi/scripts/harness-verify.mjs")]);
+	if (verifyCode !== 0) process.exit(verifyCode);
+
+	await run("pi", ["-p", "/harness-abort e2e preflight reset"]);
+
+	const harnessAuto = `/harness-auto "${task.replace(/"/g, '\\"')}"${quick ? " --quick" : ""} --risk low`;
+	const piArgs = [
+		"--session-id",
+		sessionId,
+		harnessAuto,
+	];
+
+	const env = {
+		HARNESS_ASK_USER_UI: "headless",
+		HARNESS_REVIEW_PARALLEL: process.env.HARNESS_REVIEW_PARALLEL ?? "0",
+	};
+
+	const logChild = spawn("pi", piArgs, {
+		cwd: pkgRoot,
+		env: { ...process.env, ...env },
+		stdio: ["inherit", "pipe", "pipe"],
+	});
+
+	let log = "";
+	logChild.stdout?.on("data", (c) => {
+		const s = c.toString();
+		log += s;
+		process.stdout.write(s);
+	});
+	logChild.stderr?.on("data", (c) => {
+		const s = c.toString();
+		log += s;
+		process.stderr.write(s);
+	});
+
+	const exitCode = await new Promise((resolve, reject) => {
+		logChild.on("error", reject);
+		logChild.on("close", (code) => resolve(code ?? 1));
+	});
+
+	await writeFile(logPath, log, "utf-8");
+	console.error(`harness-e2e: finished exit=${exitCode}`);
+	process.exit(exitCode);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/.pi/scripts/harness-project-toggle.mjs

@@ -118,7 +118,7 @@ function main() {
 				enabled: written.enabled,
 				path: written.path,
 				updated_at: written.updated_at,
-				reload_required: true,
+				reload_required: false,
 			},
 			null,
 			2,

package/.pi/scripts/harness-sentrux-cli.mjs

@@ -120,12 +120,28 @@ async function main() {
 		return;
 	}
 
+	function parseSentruxTimeoutMs() {
+		const raw = process.env.HARNESS_SENTRUX_TIMEOUT_MS;
+		if (raw?.trim()) {
+			const parsed = Number.parseInt(raw, 10);
+			if (Number.isFinite(parsed) && parsed > 0) return parsed;
+		}
+		return 300_000;
+	}
+
+	const timeoutMs = parseSentruxTimeoutMs();
+	let timedOut = false;
 	const child = spawn("sentrux", normalizeSentruxArgs(sentruxArgs, projectRoot), {
 		cwd: projectRoot,
 		stdio: "inherit",
 		env: process.env,
 	});
+	const timer = setTimeout(() => {
+		timedOut = true;
+		child.kill("SIGTERM");
+	}, timeoutMs);
 	child.on("error", (err) => {
+		clearTimeout(timer);
 		if (err?.code === "ENOENT") {
 			console.error("harness-sentrux-cli: sentrux not installed");
 			process.exit(127);
@@ -133,7 +149,16 @@ async function main() {
 		console.error(`harness-sentrux-cli: ${err.message}`);
 		process.exit(1);
 	});
-	child.on("close", (code) => process.exit(code ?? 1));
+	child.on("close", (code) => {
+		clearTimeout(timer);
+		if (timedOut) {
+			console.error(
+				`harness-sentrux-cli: timed out after ${timeoutMs}ms (HARNESS_SENTRUX_TIMEOUT_MS)`,
+			);
+			process.exit(124);
+		}
+		process.exit(code ?? 1);
+	});
 }
 
 main().catch((err) => {