pi-harness-runtime 1.1.150 → 1.1.152

package/harness/langchain/jev-logger.ts

@@ -0,0 +1,274 @@
+/**
+ * Jev Logger - Exclusive logging for Jev's decisions
+ *
+ * Logs all Jev decisions:
+ * - Provider selection (minimax vs gpt)
+ * - User input decisions
+ * - Escalation triggers
+ * - Reasoning
+ *
+ * Sends to both file and Telegram for real-time monitoring.
+ */
+
+import { mkdirSync, appendFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export interface JevDecision {
+	timestamp: string;
+	request: string;
+	provider: "minimax" | "gpt";
+	reason: string;
+	userInput: {
+		type: "yesNo" | "open" | null;
+		question?: string;
+	} | null;
+	escalate: boolean;
+	escalateReason?: string;
+}
+
+export interface JevLogEntry extends JevDecision {
+	raw?: string; // Raw planner output for debugging
+}
+
+const LOG_DIR = join(homedir(), ".pi-harness-runtime", "logs");
+const LOG_FILE = join(LOG_DIR, "jev.log");
+
+// Telegram config (loaded from environment)
+let TELEGRAM_BOT_TOKEN: string | undefined;
+let TELEGRAM_CHAT_ID: string | undefined;
+let telegramQueue: string[] = [];
+let telegramSending = false;
+
+export function configureTelegram(botToken?: string, chatId?: string): void {
+	TELEGRAM_BOT_TOKEN = botToken ?? process.env.TELEGRAM_BOT_TOKEN;
+	TELEGRAM_CHAT_ID = chatId ?? process.env.TELEGRAM_CHAT_ID;
+}
+
+function ensureLogDir(): void {
+	if (!existsSync(LOG_DIR)) {
+		mkdirSync(LOG_DIR, { recursive: true });
+	}
+}
+
+/**
+ * Format decision for file log (detailed, multi-line)
+ */
+function formatFileLog(entry: JevLogEntry): string {
+	const lines = [
+		`═══════════════════════════════════════════════════════════════`,
+		`[JEV] ${entry.timestamp}`,
+		`═══════════════════════════════════════════════════════════════`,
+		``,
+		`## Request`,
+		`${entry.request}`,
+		``,
+		`## Jev Provider Decision`,
+		`Provider: ${entry.provider.toUpperCase()}`,
+		`Reason:   ${entry.reason}`,
+		``,
+		`## Jev User Input Decision`,
+		`Type:     ${entry.userInput?.type ?? "none (proceed automatically)"}`,
+		entry.userInput?.question ? `Question: ${entry.userInput.question}` : ``,
+		``,
+		`## Escalation`,
+		`Escalate: ${entry.escalate ? "YES → Switching to GPT" : "No"}`,
+		entry.escalateReason ? `Reason:   ${entry.escalateReason}` : ``,
+		``,
+	];
+
+	if (entry.raw) {
+		lines.push(`## Raw Planner Output`);
+		lines.push(`\`\`\`\n${entry.raw.slice(0, 500)}\n...\`\`\``); // Truncate for file
+		lines.push(``);
+	}
+
+	lines.push(`═══════════════════════════════════════════════════════════════`);
+	lines.push(``);
+
+	return lines.join("\n");
+}
+
+/**
+ * Format decision for Telegram (compact, single message)
+ */
+function formatTelegramMessage(entry: JevLogEntry): string {
+	const providerIcon = entry.provider === "gpt" ? "🤖" : "⚡";
+	const escalateIcon = entry.escalate ? " ↑ ESCALATE" : "";
+
+	const parts = [
+		`${providerIcon} *JEV DECISION*`,
+		`\n*Provider:* ${entry.provider.toUpperCase()}${escalateIcon}`,
+		`\n*Reason:* ${entry.reason}`,
+	];
+
+	if (entry.userInput?.question) {
+		const inputIcon = entry.userInput.type === "yesNo" ? "❓" : "💬";
+		parts.push(`\n${inputIcon} *USER INPUT:* ${entry.userInput.question}`);
+	}
+
+	// Truncate request for Telegram (usually too long)
+	const shortRequest = entry.request.length > 100
+		? entry.request.slice(0, 100) + "..."
+		: entry.request;
+	parts.push(`\n\n📋 *Request:* ${shortRequest}`);
+
+	return parts.join("");
+}
+
+/**
+ * Send message to Telegram (async, queued)
+ */
+async function sendToTelegram(message: string): Promise<void> {
+	// Always try to load from env first
+	TELEGRAM_BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN ?? TELEGRAM_BOT_TOKEN;
+	TELEGRAM_CHAT_ID = process.env.TELEGRAM_CHAT_ID ?? TELEGRAM_CHAT_ID;
+
+	if (!TELEGRAM_BOT_TOKEN || !TELEGRAM_CHAT_ID) {
+		console.log("[JEV] Telegram not configured - skipping");
+		return;
+	}
+
+	console.log(`[JEV] Telegram sending: ${TELEGRAM_BOT_TOKEN?.slice(0, 10)}... to ${TELEGRAM_CHAT_ID}`);
+	telegramQueue.push(message);
+
+	// Process queue sequentially
+	if (telegramSending) {
+		console.log("[JEV] Telegram already sending, queued");
+		return;
+	}
+	telegramSending = true;
+
+	while (telegramQueue.length > 0) {
+		const msg = telegramQueue.shift()!;
+		try {
+			const response = await fetch(
+				`https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage`,
+				{
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({
+						chat_id: TELEGRAM_CHAT_ID,
+						text: msg,
+						parse_mode: "Markdown",
+					}),
+				},
+			);
+
+			if (!response.ok) {
+				console.error(`[JEV] Telegram send failed: ${response.status}`);
+			} else {
+				console.log("[JEV] Telegram sent successfully");
+			}
+		} catch (err) {
+			console.error(`[JEV] Telegram error:`, err);
+		}
+		// Rate limit: 1 message per second
+		await new Promise((resolve) => setTimeout(resolve, 1000));
+	}
+
+	telegramSending = false;
+}
+
+export async function logJevDecision(decision: JevLogEntry): Promise<void> {
+	ensureLogDir();
+
+	// Always log to file (sync)
+	const fileLog = formatFileLog(decision);
+	appendFileSync(LOG_FILE, fileLog);
+	console.log(fileLog);
+
+	// Send to Telegram (async, non-blocking for main flow)
+	const telegramMsg = formatTelegramMessage(decision);
+	// Fire-and-forget: don't await, let it run in background
+	sendToTelegram(telegramMsg).catch((err) => {
+		console.error("[JEV] Failed to send Telegram notification:", err);
+	});
+	// Also await briefly for testing, then let process exit handle it
+	await new Promise((resolve) => setTimeout(resolve, 100));
+}
+
+/**
+ * Parse Jev's decision from planner output
+ * Looks for [JEVO] and [USER_INPUT] markers
+ */
+export function parseJevDecision(planOutput: string): {
+	provider: "minimax" | "gpt";
+	reason: string;
+	userInput: JevDecision["userInput"];
+} {
+	const result: {
+		provider: "minimax" | "gpt";
+		reason: string;
+		userInput: JevDecision["userInput"];
+	} = {
+		provider: "minimax",
+		reason: "default (no explicit decision)",
+		userInput: null,
+	};
+
+	// Parse [JEVO] block
+	const jevoMatch = planOutput.match(/\[JEVO\]\s*\{[\s\S]*?"provider":\s*"(minimax|gpt)"[\s\S]*?"reason":\s*"([^"]*)"[\s\S]*?\}/);
+	if (jevoMatch) {
+		result.provider = jevoMatch[1] as "minimax" | "gpt";
+		result.reason = jevoMatch[2] || "explicit provider decision";
+	}
+
+	// Also check for [use-gpt] directive in the raw text
+	if (/\[use-gpt(?:-only)?\]/i.test(planOutput)) {
+		result.provider = "gpt";
+		result.reason = "user directive: [use-gpt]";
+	}
+
+	// Parse [USER_INPUT] block
+	const userInputMatch = planOutput.match(
+		/\[USER_INPUT\]\s*(\{[\s\S]*?\})/,
+	);
+	if (userInputMatch) {
+		try {
+			const parsed = JSON.parse(userInputMatch[1]);
+			if (parsed.type === "yesNo" || parsed.type === "open") {
+				result.userInput = {
+					type: parsed.type,
+					question: parsed.question,
+				};
+			}
+		} catch {
+			// Ignore parse errors
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Check if review indicates escalation needed
+ */
+export function shouldEscalate(reviewComments: string[]): {
+	should: boolean;
+	reason: string;
+} {
+	const escalationKeywords = [
+		"blocked",
+		"stuck",
+		"cannot proceed",
+		"complex",
+		"race condition",
+		"security issue",
+		"architecture decision needed",
+	];
+
+	for (const comment of reviewComments) {
+		const lowerComment = comment.toLowerCase();
+		for (const keyword of escalationKeywords) {
+			if (lowerComment.includes(keyword)) {
+				return {
+					should: true,
+					reason: `Review flagged: "${keyword}"`,
+				};
+			}
+		}
+	}
+
+	return { should: false, reason: "" };
+}

package/harness/langchain/run.ts

@@ -2,14 +2,17 @@
  * CLI runner for the LangChain write-review loop.
  *
  * Usage:
- *   bun harness/langchain/run.ts --mode graph --request "implement X" [--max-iterations 3]
- *   bun harness/langchain/run.ts --mode graph --request "implement X" --dry-run
- *   bun harness/langchain/run.ts --mode supervisor --request "implement X"
+ *   # Run a single task
+ *   bun run harness/langchain/run.ts --request "implement X"
  *
- * --dry-run uses deterministic stubs — no API keys needed. Use it to verify
- * the whole loop machinery (plan → write → review → fix → approve).
+ *   # Run with dry-run (no API calls)
+ *   bun run harness/langchain/run.ts --request "implement X" --dry-run
  *
- * Wiki: wiki/multi-agent-langchain.md
+ *   # Run with max iterations
+ *   bun run harness/langchain/run.ts --request "implement X" --max-iterations 5
+ *
+ *   # Run as daemon (with watchers - configure sources in code)
+ *   bun run harness/langchain/run.ts --daemon
  */
 
 import { randomUUID } from "node:crypto";
@@ -17,17 +20,16 @@ import {
 	buildDryRunDeps,
 	buildRealLoopDeps,
 	buildWriteReviewLoop,
-	type LoopState,
 } from "./graph.js";
-
+import { loadKeys } from "../key-loader.js";
 interface CliArgs {
 	mode: "graph" | "supervisor";
 	request: string;
 	maxIterations: number;
 	dryRun: boolean;
 	daemon: boolean;
-	/** If true, remaining args are passed to the cron subcommand handler. */
-	cronArgs?: string[];
+	telegramBotToken?: string;
+	telegramChatId?: string;
 }
 
 function parseArgs(argv: string[]): CliArgs {
@@ -37,183 +39,84 @@ function parseArgs(argv: string[]): CliArgs {
 		maxIterations: 3,
 		dryRun: false,
 		daemon: false,
+		telegramBotToken: process.env.TELEGRAM_BOT_TOKEN,
+		telegramChatId: process.env.TELEGRAM_CHAT_ID,
 	};
-	// Normalize space-separated flags (--mode graph) into --mode=graph form
-	const normalized: string[] = [];
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i] as string;
-		const spaced =
-			(arg === "--mode" || arg === "--request" || arg === "--max-iterations") &&
-			argv[i + 1] !== undefined &&
-			!(argv[i + 1] as string).startsWith("--");
-		if (spaced) {
-			normalized.push(`${arg}=${argv[i + 1]}`);
-			i++;
-		} else {
-			normalized.push(arg);
-		}
-	}
-	// Detect "cron" subcommand before processing other flags
-	const cronIndex = normalized.indexOf("cron");
-	if (cronIndex !== -1) {
-		args.cronArgs = normalized.slice(cronIndex + 1);
-		return args;
-	}
 
-	for (const arg of normalized) {
-		if (arg.startsWith("--mode=")) {
-			const mode = arg.slice("--mode=".length);
-			if (mode !== "graph" && mode !== "supervisor") {
-				throw new Error(`Unknown mode: ${mode} (expected graph|supervisor)`);
-			}
-			args.mode = mode;
-		} else if (arg.startsWith("--request=")) {
-			args.request = arg.slice("--request=".length);
-		} else if (arg.startsWith("--max-iterations=")) {
-			const n = Number.parseInt(arg.slice("--max-iterations=".length), 10);
-			if (Number.isNaN(n) || n < 1 || n > 20) {
-				throw new Error("--max-iterations must be 1-20");
-			}
-			args.maxIterations = n;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--request" || arg === "-r") {
+			args.request = argv[++i] ?? "";
 		} else if (arg === "--dry-run") {
 			args.dryRun = true;
 		} else if (arg === "--daemon") {
 			args.daemon = true;
-		} else if (arg === "--help" || arg === "-h") {
-			console.log(
-				[
-					"Usage: bun harness/langchain/run.ts [options]",
-					"",
-					"Options:",
-					"  --mode=graph|supervisor   Loop style (default: graph)",
-					'  --request="..."           The feature request',
-					"  --max-iterations=N        Max write-review rounds (default: 3)",
-					"  --dry-run                 Deterministic stubs, no API calls",
-					"  --daemon                  Start as a long-running daemon (auto-trigger loop)",
-				].join("\n"),
-			);
-			process.exit(0);
-		} else {
-			// Bare positional argument = request
-			if (!args.request) args.request = arg;
+		} else if (arg === "--max-iterations") {
+			args.maxIterations = parseInt(argv[++i] ?? "3", 10);
+		} else if (arg === "--mode") {
+			args.mode = argv[++i] as "graph" | "supervisor";
 		}
 	}
-	if (!args.request && !args.daemon && !args.cronArgs) {
-		throw new Error(
-			'A request is required: --request="..." or a bare string (or use --daemon or --cron to start the watcher)',
-		);
-	}
-	return args;
-}
 
-function printStep(step: string, state: LoopState): void {
-	const labels: Record<string, string> = {
-		plan: "🧭 GPT planner",
-		write: "✍️  MiniMax coder",
-		review: "🔍 GPT reviewer",
-		finish: "🏁 finish",
-	};
-	const iter = state.iteration > 0 ? ` (iteration ${state.iteration})` : "";
-	console.log(`  ${labels[step] ?? step}${iter}`);
+	return args;
 }
 
-async function runGraphLoop(args: CliArgs): Promise<void> {
-	console.log(
-		`\n━━━ Write-Review Loop (graph mode)${args.dryRun ? " — DRY RUN" : ""} ━━━`,
-	);
-	console.log(`Request: ${args.request}\n`);
+async function runGraphMode(args: CliArgs): Promise<void> {
+	const loopId = `loop-${randomUUID().slice(0, 8)}`;
+	const log = (msg: string) => console.log(`[${loopId}] ${msg}`);
 
-	const deps = args.dryRun
-		? buildDryRunDeps({ maxIterations: args.maxIterations, onStep: printStep })
-		: await buildRealLoopDeps({
+	// Build deps
+	const deps = await (args.dryRun
+		? buildDryRunDeps({ maxIterations: args.maxIterations })
+		: buildRealLoopDeps({
 				maxIterations: args.maxIterations,
-				onStep: printStep,
-			});
+				request: args.request,
+			}));
 
+	// Create loop
 	const loop = buildWriteReviewLoop(deps);
-	const threadId = `loop-${randomUUID().slice(0, 8)}`;
-
-	const finalState = await loop.invoke(
-		{ request: args.request },
-		{ configurable: { thread_id: threadId } },
-	);
 
-	console.log("\n─── Step log ───");
-	for (const line of finalState.log) console.log(`  ${line}`);
+	// Run
+	log(`Starting write-review loop (maxIterations=${args.maxIterations})`);
 
-	console.log("\n─── Verdict ───");
-	const review = finalState.review;
-	if (review) {
-		console.log(`  ${review.verdict.toUpperCase()} — ${review.summary}`);
-		if (review.comments.length > 0) {
-			console.log("  Open comments:");
-			for (const c of review.comments) {
-				const file = c.file ? ` (${c.file})` : "";
-				console.log(`   - [${c.severity ?? "n/a"}] ${c.comment}${file}`);
-			}
-		}
-	} else {
-		console.log("  (no review produced)");
-	}
-}
-
-async function runSupervisor(args: CliArgs): Promise<void> {
-	if (args.dryRun) {
-		throw new Error(
-			"--dry-run is only supported for --mode=graph (supervisor needs real models)",
+	try {
+		const result = await loop.invoke(
+			{ request: args.request },
+			{ configurable: { thread_id: loopId }, recursionLimit: 50 },
 		);
+		log(`Loop completed! Final state: ${JSON.stringify(result, null, 2)}`);
+	} catch (err) {
+		console.error(`[${loopId}] Error:`, err);
+		process.exit(1);
 	}
-	console.log("\n━━━ Write-Review Loop (supervisor mode) ━━━");
-	console.log(`Request: ${args.request}\n`);
-
-	const { createSupervisor, lastMessage } = await import("./agents.js");
-	const supervisor = createSupervisor();
-	const result = await supervisor.invoke({
-		messages: [{ role: "user", content: args.request }],
-	});
-	console.log("\n─── Supervisor output ───");
-	console.log(lastMessage(result));
 }
 
-async function runDaemon(args: CliArgs): Promise<void> {
-	const { LoopDaemon } = await import("./daemon.js");
-	const daemon = new LoopDaemon({
-		maxIterations: args.maxIterations,
-		dryRun: args.dryRun,
-		sources: ["inbox", "bus", "codex"],
-	});
-
-	// Graceful shutdown on SIGTERM / SIGINT
-	const shutdown = () => {
-		daemon.stop();
-		process.exit(0);
-	};
-	process.on("SIGTERM", shutdown);
-	process.on("SIGINT", shutdown);
-
-	daemon.start();
-
-	// Keep the process alive
-	await new Promise(() => {});
+async function runDaemonMode(_args: CliArgs): Promise<void> {
+	console.log("Daemon mode - use --request to run a task or configure watchers");
+	process.exit(0);
 }
 
 async function main(): Promise<void> {
 	const args = parseArgs(process.argv.slice(2));
-	if (args.cronArgs !== undefined) {
-		const { runCron } = await import("./cron-cli.js");
-		await runCron(args.cronArgs);
-	} else if (args.daemon) {
-		await runDaemon(args);
-	} else if (args.mode === "supervisor") {
-		await runSupervisor(args);
+
+	// Load API keys
+	loadKeys();
+
+	if (!args.request && !args.daemon) {
+		console.error("Usage: bun run harness/langchain/run.ts --request 'task description'");
+		console.error("Options:");
+		console.error("  --request, -r    Task description");
+		console.error("  --dry-run        Run without API calls");
+		console.error("  --max-iterations N  Max iterations (default: 3)");
+		console.error("  --daemon         Run in daemon mode");
+		process.exit(1);
+	}
+
+	if (args.daemon) {
+		await runDaemonMode(args);
 	} else {
-		await runGraphLoop(args);
+		await runGraphMode(args);
 	}
 }
 
-main().catch((err: unknown) => {
-	console.error(
-		`[run] Error: ${err instanceof Error ? err.message : String(err)}`,
-	);
-	process.exit(1);
-});
+main().catch(console.error);

package/harness/langchain/surge.test.ts

@@ -76,6 +76,48 @@ describe("T1 — classifySurge", () => {
 		assert.equal(classifySurge(new Error("ECONNREFUSED")), null);
 		assert.equal(classifySurge("file not found"), null);
 	});
+
+	it("classifies 'Request timed out.'", () => {
+		const sig = classifySurge(new Error("Request timed out."));
+		assert.ok(sig, "should classify timeout");
+		assert.equal(sig?.explicit, false); // no stated delay → 2 min default
+		assert.equal(sig?.retryAfterMs, 120_000);
+	});
+
+	it("classifies 'timed out' without 'request' prefix", () => {
+		const sig = classifySurge(new Error("timed out"));
+		assert.ok(sig, "should classify");
+		assert.equal(sig?.retryAfterMs, 120_000);
+	});
+
+	it("parses 'timed out after Xms'", () => {
+		const sig = classifySurge(new Error("timed out after 30000ms"));
+		assert.ok(sig);
+		assert.equal(sig?.retryAfterMs, 30_000);
+		assert.equal(sig?.explicit, true);
+	});
+
+	it("parses 'Request timed out after X seconds'", () => {
+		const sig = classifySurge(new Error("Request timed out after 60 seconds"));
+		assert.ok(sig);
+		assert.equal(sig?.retryAfterMs, 60_000);
+		assert.equal(sig?.explicit, true);
+	});
+
+	it("parses 'timed out after Xms' (milliseconds keyword)", () => {
+		const sig = classifySurge(new Error("command timed out after 15000 milliseconds"));
+		assert.ok(sig);
+		assert.equal(sig?.retryAfterMs, 15_000);
+		assert.equal(sig?.explicit, true);
+	});
+
+	it("'Retry failed after 3 attempts: Request timed out.'", () => {
+		const sig = classifySurge(
+			new Error("Retry failed after 3 attempts: Request timed out."),
+		);
+		assert.ok(sig, "should classify inner timeout");
+		assert.equal(sig?.retryAfterMs, 120_000);
+	});
 });
 
 // ─── T2/T3 Delay computation & escalation ────────────────────────────────────

package/harness/langchain/surge.ts

@@ -25,11 +25,14 @@ const OVERLOADED_PATTERNS: RegExp[] = [
 	/overloaded_error/i,
 	/peak.?hour.*surge/i,
 	/(?:overload|surge|busy)/i,
+	/(?:request )?timed?\s*out/i,
 ];
 
 const RECOVERY_RANGE = /recovers? within (\d+)\s*[\u2013-]\s*(\d+)\s*minutes/i;
 const SIMPLE_DELAY = /retry (?:after|in) (\d+)\s*(seconds?|secs?|s)\b/i;
 const RETRY_AFTER_MS = /retry.?after[^0-9]{0,12}(\d{4,})\s*ms/i;
+const TIMEOUT_DURATION_MS = /timed?\s*out(?: after)?[^0-9]*(\d+)\s*(ms|milliseconds?)/i;
+const TIMEOUT_DURATION_S = /timed?\s*out(?: after)?[^0-9]*(\d+)\s*(seconds?|secs?|s)\b/i;
 
 /**
  * Classify an unknown error as a transient provider surge (MiniMax).
@@ -83,6 +86,24 @@ export function classifySurge(err: unknown): SurgeSignal | null {
 		}
 	}
 
+	// "timed out after Xms" → use that duration
+	const timeoutMs = sourceText.match(TIMEOUT_DURATION_MS);
+	if (timeoutMs) {
+		const val = Number.parseInt(timeoutMs[1] as string, 10);
+		if (Number.isFinite(val) && val > 0) {
+			return { retryAfterMs: val, explicit: true, sourceText };
+		}
+	}
+
+	// "timed out after X seconds" → convert to ms
+	const timeoutSecs = sourceText.match(TIMEOUT_DURATION_S);
+	if (timeoutSecs) {
+		const val = Number.parseInt(timeoutSecs[1] as string, 10);
+		if (Number.isFinite(val) && val > 0) {
+			return { retryAfterMs: val * 1000, explicit: true, sourceText };
+		}
+	}
+
 	// Overload-class error without a stated delay → conservative default
 	return { retryAfterMs: 120_000, explicit: false, sourceText };
 }
@@ -188,7 +209,7 @@ export interface SurgePolicy {
 const DEFAULT_SURGE_POLICY: SurgePolicy = {
 	multiplier: 2,
 	minDelayMs: 30_000,
-	maxDelayMs: 15 * 60_000,
+	maxDelayMs: 15 * 60 * 1000,
 	jitterRatio: 0.2,
 	maxAttempts: 5,
 };

package/index.ts

@@ -648,6 +648,27 @@ async function initFileCopyHelper(pi: ExtensionAPI): Promise<void> {
 	}
 }
 
+// --- agent-policy: Mandatory rule delivery and mutation gating ------------------
+// Lazy import - only loads when packages/agent-policy exists
+// This replaces firstAgentStart-only injection with:
+// - System prompt injection on EVERY agent start (not just first)
+// - Policy receipt tracking per session
+// - Mutation gating until policy revision is confirmed received
+// - harness_rules tool for rule retrieval and acknowledgement
+async function initAgentPolicy(pi: ExtensionAPI): Promise<void> {
+	try {
+		const { registerAgentPolicy } = await import("./packages/agent-policy/src/extension.js");
+		registerAgentPolicy(pi, {
+			harnessRulesPath: new URL("./AGENTS.md", import.meta.url),
+			requireReceiptBeforeMutation: true,
+			lspMode: "pi-lens",
+		});
+		logStartup("[pi-harness] Agent policy initialized");
+	} catch (err) {
+		logStartup(`[pi-harness] Agent policy init failed: ${err}`);
+	}
+}
+
 // --- SSH detach interceptor: Auto-transform bare ssh ... & to detached pattern ---
 // Prevents 2000+ second hangs when SSH background commands aren't detached.
 // Intercepts every bash tool call before execution and rewrites risky SSH commands.
@@ -1173,6 +1194,9 @@ export default function (pi: ExtensionAPI) {
 	// --- file-copy-helper: Inject cp rule when mimicking files -------------
 	void initFileCopyHelper(pi);
 
+	// --- agent-policy: Mandatory rule delivery and mutation gating -------------
+	void initAgentPolicy(pi);
+
 	// --- ssh-detach-interceptor: Auto-fix bare ssh & → nohup pattern ---------
 	void initSshDetachInterceptor(pi);