pi-harness-runtime 1.1.458 → 1.1.460

package/index.ts

@@ -26,6 +26,7 @@ import {
 	formatKeyFileFixes,
 	formatKeyPermissionFixes,
 	selectKeyFileFixes,
+	secureKeyTree,
 	type KeyFileAuditResult,
 } from "./harness/key-file-audit.ts";
 import { renderDetailLines } from "./harness/startup-lines.ts";
@@ -41,7 +42,17 @@ import {
 	relayShouldBeReported,
 } from "./harness/startup-report.ts";
 import { localSkillsReport, skillsReport } from "./harness/skills-startup.ts";
+import {
+	PendingQuestionCountdown,
+	type CountdownView,
+} from "./harness/pending-countdown.ts";
 import { isChannelDisabled, setChannelDisabled } from "./harness/notification-settings.ts";
+// The Honcho contract lives with the Honcho integration. A type-only import
+// is erased at runtime, so the startup keeps loading the module lazily.
+import type {
+	HonchoInitResult,
+	HonchoMcpRegistrar,
+} from "./harness/honcho-init.ts";
 import { UsageTracker } from "./tracker.ts";
 import { MirrorStore, type MirrorRecord } from "./mirror.ts";
 import { MiniMaxQuotaScraper } from "./harness/e2e/minimax-quota-scraper.js";
@@ -211,17 +222,44 @@ function getKeyFileAudit(): KeyFileAuditResult | null {
  * is a list nobody runs. The command is never executed here.
  */
 function reportExposedKeyFiles(): void {
-	const audit = getKeyFileAudit();
-	const exposed = audit?.exposed ?? [];
-	const exposedDirectories = audit?.exposedDirectories ?? [];
+	let audit = getKeyFileAudit();
+	let exposed = audit?.exposed ?? [];
+	let exposedDirectories = audit?.exposedDirectories ?? [];
 	if (exposed.length === 0 && exposedDirectories.length === 0) return;
+
+	// Key files belong to this app and are private by design. Repair unsafe
+	// Unix permissions automatically; keep the actionable warning only when
+	// the platform cannot express the repair or a path cannot be changed.
+	const repair = secureKeyTree(harnessKeysDir());
+	if (repair.supported) {
+		try {
+			audit = auditKeyFiles({ keysDir: harnessKeysDir() });
+			keyFileAudit = audit;
+		} catch {
+			// Preserve the original findings if the verification scan fails.
+		}
+		exposed = audit?.exposed ?? exposed;
+		exposedDirectories = audit?.exposedDirectories ?? exposedDirectories;
+		if (exposed.length === 0 && exposedDirectories.length === 0) {
+			addHarnessMessage(
+				"Keys",
+				`permissions secured automatically (${repair.securedFiles} files, ${repair.securedDirectories} directories)`,
+				"ok",
+			);
+			return;
+		}
+	}
+
 	const report = exposedKeyFilesReport({
 		exposed,
 		exposedDirectories,
 		fixes: formatKeyPermissionFixes({ keysDir: harnessKeysDir() }),
 	});
 	if (!report) return;
-	addHarnessMessage(report.label, report.text, report.status, report.details);
+	const failedPaths = repair.failedPaths.length > 0
+		? [`Could not change permissions for: ${repair.failedPaths.join(", ")}`]
+		: [];
+	addHarnessMessage(report.label, report.text, report.status, [...failedPaths, ...report.details]);
 }
 
 /**
@@ -258,6 +296,9 @@ const sharedState = {
 	validationLedger: null as unknown,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	updateAutoContinueStatus: null as any,
+	// The live countdown of the pending question. The channels stop it when
+	// a human answer arrives.
+	pendingCountdown: null as PendingQuestionCountdown | null,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	pqController: null as any,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -301,6 +342,8 @@ function applyChannelApproval(
 	// cleared after a successful resolution.
 	sharedState.waitingForUserSince = null;
 	sharedState.updateAutoContinueStatus?.("IDLE");
+	// The countdown of the answered question is over with it.
+	sharedState.pendingCountdown?.stop();
 
 	if (result.resolution === "yes") {
 		(sharedState.todoContinuationController as any)?.resume?.();
@@ -898,6 +941,12 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 		let lastUserMessage: Date | null = null;
 		let autoContinueTimer: NodeJS.Timeout | null = null;
 		let _inferenceInProgress = false; // Track for overlap prevention
+		// The timing of the wait. The countdown in the status row and the
+		// decision of the judge use the same constants, so the displayed
+		// deadline and the decision can never drift apart.
+		const AUTO_CONTINUE_INTERVAL_MS = 60 * 1000; // Fallback poll: every minute
+		const MIN_WAIT_MINUTES = 5; // Minimum wait before auto-continue
+		const MAX_WAIT_MINUTES = 30; // After this the work pauses instead of waiting
 		// A continuation was dispatched and its turn has not settled yet.
 		// The gate owns that state: the status stays "RUN" until the turn
 		// settles, and no timer may clear it in the meantime.
@@ -989,6 +1038,15 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 			}
 		});
 		let _sessionId = Date.now().toString(36); // Track session for cancellation
+		// The session of the Pi runtime. A countdown belongs to the session
+		// that asked the question.
+		let _piSessionId = "";
+		// The session the running countdown belongs to. A countdown of a
+		// session that is gone must not draw its status any more.
+		let _countdownSessionId = "";
+		// The request the row of the footer belongs to. A countdown that
+		// stops must not clear the row of a newer question.
+		let _countdownRowRequestId: string | null = null;
 		let _lastNotifiedQuestion = ""; // Track last question to prevent repeat notifications
 		let _completedNotifiedFor: string | null = null; // Track completion notification deduplication
 
@@ -1014,36 +1072,164 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 			ERROR: "Auto-continue unavailable",
 		} as const;
 
+		// The live countdown of the pending question.
+		//
+		// It owns the deadline of the wait: it shows the remaining time in
+		// the status row once per second and starts the decision of the
+		// judge exactly at the deadline. The fallback poll only takes over
+		// when there is no countdown, so a decision is never started twice.
+		const pendingCountdown = new PendingQuestionCountdown({
+			// The two policies of the wait belong to the countdown, so the
+			// displayed deadline and the deadline of the judge cannot drift
+			// apart.
+			waitMinutes: MIN_WAIT_MINUTES,
+			recheckIntervalMs: AUTO_CONTINUE_INTERVAL_MS,
+			render: (view: CountdownView) => {
+				_countdownRowRequestId = view.requestId;
+				updateAutoContinueStatus(
+					"WAITING",
+					view.requestId.slice(0, 8),
+					view.mode === "recheck"
+						? `Jev will recheck in ${view.remaining}`
+						: `Jev decision in ${view.remaining}`,
+				);
+			},
+			onDeadline: (requestId: string) => {
+				logToFile("[auto-continue]", "The decision deadline was reached:", requestId);
+				checkAndAutoContinue("countdown")
+					.then(() => {
+						// The decision did not start - another one was still in
+						// flight, or the wait was gone before it ran. The
+						// deadline is not lost: the countdown is armed again
+						// and the decision follows.
+						if (pendingCountdown.fired && pendingCountdown.requestId === requestId) {
+							pendingCountdown.startRecheck(requestId);
+						}
+					})
+					.catch((error) => {
+						logToFile("[auto-continue]", "The decision failed:", oneLineError(error));
+						// The decision did not run: the countdown releases the
+						// wait, so the fallback poll can take over again.
+						pendingCountdown.stop();
+					});
+			},
+			isPending: (requestId: string) => {
+				// The wait must still belong to the request: a late tick of
+				// an answered or replaced question must not draw its status
+				// and must not trigger a decision.
+				if (!waitingForUserSince) return false;
+				if (_countdownSessionId !== _piSessionId) return false;
+				const current = sharedState.pqController?.getCurrentQuestion?.();
+				if (!current) return false;
+				return (
+					current.requestId === requestId &&
+					(current.state === "pending" || current.state === "evaluating")
+				);
+			},
+			onStop: (requestId: string | null) => {
+				// The countdown is over: the row is cleared with it, so no
+				// row claims a decision that is not due any more. Only the row
+				// of that countdown is cleared: a row of another state - the
+				// judge continues, for example - belongs to that state, and
+				// the row of a newer question belongs to that question.
+				if (_countdownRowRequestId && requestId && _countdownRowRequestId !== requestId) {
+					return;
+				}
+				_countdownRowRequestId = null;
+				if (_currentAutoContinueState.startsWith("[WAIT]")) {
+					_currentAutoContinueState = "";
+					_setAutoContinueStatus?.(undefined);
+				}
+			},
+			onError: (error: unknown) => {
+				logToFile("[auto-continue]", "The countdown failed:", oneLineError(error));
+			},
+		});
+		sharedState.pendingCountdown = pendingCountdown;
+
 		// Wire shared state for callback handlers
 		sharedState.waitingForUserSince = waitingForUserSince;
 		sharedState.updateAutoContinueStatus = updateAutoContinueStatus;
 
-		// Update auto-continue status in TUI footer
-		function updateAutoContinueStatus(state: keyof typeof AC_STATE_MESSAGES, requestId?: string): void {
-			if (!_setAutoContinueStatus) return;
+		/**
+		 * Start the countdown of a pending question.
+		 *
+		 * The deadline of the decision is derived from the wait that is
+		 * already running, so the displayed deadline and the decision of
+		 * the judge can never drift apart.
+		 */
+		function startPendingCountdown(requestId: string): void {
+			_countdownSessionId = _piSessionId;
+			const startedAt = waitingForUserSince?.getTime() ?? Date.now();
+			pendingCountdown.start(requestId, startedAt);
+		}
 
+		/**
+		 * Start the countdown of the next attempt.
+		 *
+		 * The judge asked to wait longer: the countdown counts down to the
+		 * next attempt instead of to the deadline of the decision.
+		 */
+		function startRecheckCountdown(requestId: string): void {
+			_countdownSessionId = _piSessionId;
+			pendingCountdown.startRecheck(requestId);
+		}
+
+		// Update auto-continue status in TUI footer
+		function updateAutoContinueStatus(
+			state: keyof typeof AC_STATE_MESSAGES,
+			requestId?: string,
+			detail?: string,
+		): void {
 			const message = AC_STATE_MESSAGES[state];
 			if (state === "IDLE") {
-				// Clear status
-				_setAutoContinueStatus(undefined);
-				_currentAutoContinueState = "";
-			} else {
-				const statusText = requestId
-					? `[${AC_STATE[state]}] ${message} | ${requestId}`
-					: `[${AC_STATE[state]}] ${message}`;
-
-				// Only update if state changed (prevent flicker)
-				if (statusText !== _currentAutoContinueState) {
-					_setAutoContinueStatus(statusText);
-					_currentAutoContinueState = statusText;
+				// Only the row is cleared here: the countdown belongs to the
+				// wait, not to the row. A settled continuation must not stop
+				// the countdown of a question that the agent asked in the
+				// same turn, and it must not blank its row either.
+				if (!pendingCountdown.active) {
+					_currentAutoContinueState = "";
+					_setAutoContinueStatus?.(undefined);
 				}
+				return;
+			}
+
+			const parts = [`[${AC_STATE[state]}] ${message}`];
+			if (requestId) parts.push(requestId);
+			if (detail) parts.push(detail);
+			const statusText = parts.join(" | ");
+
+			// Only update if state changed (prevent flicker). The state is
+			// kept even without a UI binding: a session that starts without
+			// a TUI shows the current state as soon as the UI is there.
+			if (statusText !== _currentAutoContinueState) {
+				_currentAutoContinueState = statusText;
+				_setAutoContinueStatus?.(statusText);
 			}
 		}
 
 		// Capture UI context from session_start
 		pi.on("session_start", (_event, ctx) => {
+			// The session of the runtime: the countdown of a question belongs
+			// to the session that asked it.
+			const sessionId = (
+				ctx as { sessionManager?: { getSessionId?: () => string | undefined } }
+			).sessionManager?.getSessionId?.();
+			if (typeof sessionId === "string" && sessionId) {
+				if (_piSessionId && _piSessionId !== sessionId) {
+					// The session changed: the countdown of the old session
+					// is over with it.
+					pendingCountdown.stop();
+				}
+				_piSessionId = sessionId;
+			}
 			if (ctx.hasUI && ctx.ui) {
 				_setAutoContinueStatus = ctx.ui.setStatus.bind(ctx.ui, "harness-auto-continue");
+				// A session without a TUI collected the state already: it is
+				// shown as soon as the UI is there.
+				if (_currentAutoContinueState) {
+					_setAutoContinueStatus(_currentAutoContinueState);
+				}
 			}
 
 		});
@@ -1056,6 +1242,9 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 				autoContinueTimer = null;
 			}
 
+			// The countdown of the pending question is over with the session.
+			pendingCountdown.stop();
+
 			// Clear UI binding and status
 			if (_setAutoContinueStatus) {
 				_setAutoContinueStatus(undefined);
@@ -1114,6 +1303,8 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 			waitingForUserSince = null;
 			sharedState.waitingForUserSince = null;
 			_lastNotifiedQuestion = "";
+			// The question is answered: the countdown of the wait is over.
+			pendingCountdown.stop();
 			updateAutoContinueStatus("IDLE");
 			// Dispatch answer to Pi
 			const message = answer === "yes" ? "yes" : "not yet";
@@ -1190,8 +1381,10 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 					// Use question.requestId as the jobId for callback matching
 					const questionJobId = question.requestId;
 
-					// Update TUI status - use short ID for display
-					updateAutoContinueStatus("WAITING", questionJobId.slice(0, 8));
+					// The status row counts down to the decision of the judge.
+					// The countdown is bound to this request, so a newer
+					// question replaces it.
+					startPendingCountdown(questionJobId);
 
 				// Get task context for additional info
 				const taskContext = await getTaskContext().catch(() => ({ total: 0, completed: 0, remaining: [] as string[] }));
@@ -1354,6 +1547,9 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 				if (waitingForUserSince) {
 					waitingForUserSince = null;
 					_lastNotifiedQuestion = "";
+					// The user answered in Pi: the countdown of the wait is
+					// over with it.
+					pendingCountdown.stop();
 					updateAutoContinueStatus("IDLE");
 					// Cancel pending question on user response
 					// (User answered via Pi instead of button)
@@ -1363,18 +1559,22 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 		});
 
 		// Periodic check for auto-continue decision
-		const AUTO_CONTINUE_INTERVAL_MS = 60 * 1000; // Check every 1 minute
-		const MIN_WAIT_MINUTES = 5; // Minimum wait before auto-continue
-		const MAX_WAIT_MINUTES = 30; // After this the work pauses instead of waiting
 
-		const checkAndAutoContinue = async () => {
+		const checkAndAutoContinue = async (source: "countdown" | "poll" = "poll") => {
 			// Prevent overlap if inference is already in progress
 			if (_inferenceInProgress) {
+				// A deadline that was blocked is armed again by the caller of
+				// the countdown, so the decision is not lost.
 				return;
 			}
 
 			if (!waitingForUserSince) return;
 
+			// The countdown owns the wait while it runs: the fallback poll
+			// only takes over when there is no countdown, so the decision is
+			// never started twice.
+			if (source === "poll" && pendingCountdown.active) return;
+
 			// Capture session ID at check time for post-inference validation
 			const checkSessionId = _sessionId;
 			// Use same hash algorithm as detection
@@ -1436,6 +1636,9 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 				if (taskContext.total === 0 && !hasPendingQuestion) {
 					logToFile("[auto-continue]", "No tasks and no pending questions, skipping auto-continue check");
 					_inferenceInProgress = false;
+					// The countdown is over: the fallback poll takes over the
+					// next attempt.
+					pendingCountdown.stop();
 					return;
 				}
 
@@ -1590,15 +1793,20 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 						if (waitBelongsToRequest(questionContext?.requestId)) {
 							waitingForUserSince = null;
 							sharedState.waitingForUserSince = null;
+							// The request expired: the countdown of the wait
+							// is over with it.
+							pendingCountdown.stop();
 							updateAutoContinueStatus("IDLE");
 						}
 					} else {
-						// The request stays open: the next poll asks again
-						// until the deadline closes it.
-						updateAutoContinueStatus(
-							"WAITING",
-							questionContext?.requestId.slice(0, 8),
-						);
+						// The request stays open: the countdown counts down to
+						// the next check, so the retry does not wait for the
+						// fallback poll.
+						if (questionContext?.requestId) {
+							startRecheckCountdown(questionContext.requestId);
+						} else {
+							updateAutoContinueStatus("WAITING");
+						}
 					}
 				} else {
 					// Close the question with the Jev decision. The buttons of
@@ -1635,6 +1843,9 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 							waitingForUserSince = null;
 							sharedState.waitingForUserSince = null;
 							_lastNotifiedQuestion = "";
+							// The stale decision is discarded: the countdown
+							// of the wait is over with it.
+							pendingCountdown.stop();
 							updateAutoContinueStatus("IDLE");
 						} else {
 							logToFile(
@@ -1658,6 +1869,9 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 							waitingForUserSince = null;
 							sharedState.waitingForUserSince = null;
 							_lastNotifiedQuestion = "";
+							// The work pauses for a human: the countdown of
+							// the wait is over with it.
+							pendingCountdown.stop();
 							updateAutoContinueStatus("IDLE");
 						}
 						return;
@@ -1691,6 +1905,8 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 					waitingForUserSince = null;
 					sharedState.waitingForUserSince = null;
 					_lastNotifiedQuestion = "";
+					// The question is closed: the countdown of the wait is over.
+					pendingCountdown.stop();
 
 					// The status stays "RUN" until the turn that the steer
 					// started has settled. A timer would clear it while the
@@ -1701,6 +1917,9 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 				_inferenceInProgress = false;
 			} catch {
 				_inferenceInProgress = false;
+				// The countdown is over: the fallback poll takes over the next
+				// attempt.
+				pendingCountdown.stop();
 				updateAutoContinueStatus("ERROR");
 				addHarnessMessage("Jev", "auto-continue evaluation failed", "err", [
 					"How to fix: Check logs at /tmp/pi-harness.log for API errors",
@@ -2074,7 +2293,10 @@ async function initAutoContinue(pi: ExtensionAPI): Promise<void> {
 		});
 
 		// Start periodic check
-		autoContinueTimer = setInterval(checkAndAutoContinue, AUTO_CONTINUE_INTERVAL_MS);
+		autoContinueTimer = setInterval(
+			() => checkAndAutoContinue("poll"),
+			AUTO_CONTINUE_INTERVAL_MS,
+		);
 		if (jevKeyMissing) {
 			// Without a provider the health check cannot run. The missing-key
 			// message (with its fix commands) stays the visible one.
@@ -3220,39 +3442,65 @@ function initConsoleGuard(pi: ExtensionAPI): void {
 }
 
 // --- honcho-memory: Honcho MCP for peer/user memory via https://mcp.honcho.dev ------
-// Registers Honcho MCP server and implements automatic memory lifecycle:
+// Registers the Honcho MCP server with Pi's NATIVE MCP support and implements
+// the automatic memory lifecycle:
 // - Ingest sanitized messages on completed turns
 // - Retrieve relevant context before agent execution
 // - Deduplication by message ID
 // - Bounded context injection with provenance
 
+/**
+ * The contract of the Honcho integration module.
+ *
+ * The module is loaded at runtime, so the shape of its exports is declared
+ * here: this is the only part TypeScript cannot check for us.
+ */
+interface HonchoModule {
+	initHoncho: (options: {
+		apiKey?: string;
+		pi?: HonchoMcpRegistrar;
+	}) => Promise<HonchoInitResult>;
+	registerHonchoLifecycle: (pi: unknown) => void;
+	/** The credential: the environment wins over the key file. */
+	loadHonchoApiKey: () => string | undefined;
+	/** Removes the credential from a text. */
+	redactHonchoKey: (text: string, apiKey: string) => string;
+}
+
 async function initHoncho(pi: ExtensionAPI): Promise<void> {
 	addHarnessMessage("Honcho", "initializing", "wait");
+	let apiKey = "";
+	let honcho: HonchoModule | null = null;
 	try {
-	// Import new Honcho integration module
-	const { initHoncho: honchoInit, registerHonchoLifecycle } = await import("./harness/honcho-init.js");
+	// Import the Honcho integration module.
+	honcho = (await import("./harness/honcho-init.js")) as unknown as HonchoModule;
 
-	// Check for API key
-	const { readFileSync, existsSync } = await import("node:fs");
-	const home = process.env.HOME || process.env.USERPROFILE || homedir();
-	const keyPath = `${home}/.pi-harness-runtime/keys/honcho-api-key.txt`;
+	// The credential comes from the loader of the module: the environment
+	// variable wins over the key file, and the file is the per-user default.
+	apiKey = honcho.loadHonchoApiKey() ?? "";
+	if (!apiKey) {
+		// A key file that exists but is empty is a different advice than a
+		// missing file.
+		const { readFileSync, existsSync } = await import("node:fs");
+		const home = process.env.HOME || process.env.USERPROFILE || homedir();
+		const keyPath = `${home}/.pi-harness-runtime/keys/honcho-api-key.txt`;
+		const emptyFile = existsSync(keyPath) && readFileSync(keyPath, "utf8").trim() === "";
+
+		if (emptyFile) {
+			logStartup("[pi-harness] Honcho: API key is empty — skipping");
+			addHarnessMessage("Honcho", "API key empty", "warn", [
+				...keyFileFixesOrFallback("Honcho", ["API key"]),
+				"Then reload Pi.",
+			]);
+			return;
+		}
 
-	if (!existsSync(keyPath)) {
 		logStartup("[pi-harness] Honcho not configured:");
 		logStartup("[pi-harness]   Get key: https://app.honcho.dev/api-keys");
 		logStartup(`[pi-harness]   Then: echo "{api-key}" > ~/.pi-harness-runtime/keys/honcho-api-key.txt`);
 		addHarnessMessage("Honcho", "API key missing", "warn", [
 			...keyFileFixesOrFallback("Honcho", ["API key"]),
-			"Then reload Pi.",
-		]);
-		return;
-	}
-
-	const apiKey = readFileSync(keyPath, "utf8").trim();
-	if (!apiKey) {
-		logStartup("[pi-harness] Honcho: API key is empty — skipping");
-		addHarnessMessage("Honcho", "API key empty", "warn", [
-			...keyFileFixesOrFallback("Honcho", ["API key"]),
+			"Get a key: https://app.honcho.dev/api-keys",
 			"Then reload Pi.",
 		]);
 		return;
@@ -3260,27 +3508,130 @@ async function initHoncho(pi: ExtensionAPI): Promise<void> {
 
 		// Register lifecycle hooks using the new integration
 		// SAFETY: pi.on accepts these event names at runtime
-		registerHonchoLifecycle(pi as unknown as { on: (event: string, handler: (...args: unknown[]) => void | Promise<void>) => void });
-
-		// Initialize Honcho with the API key and pi.events
-		// SAFETY: pi.events implements the required on/emit interface
-		const result = await honchoInit({ apiKey, piEvents: pi.events });
+		honcho.registerHonchoLifecycle(pi as unknown as { on: (event: string, handler: (...args: unknown[]) => void | Promise<void>) => void });
+
+		// Initialize Honcho with the API key. The integration uses Pi's own MCP
+		// client, so no event adapter is passed any more. It also registers
+		// the MCP server with the extension API of Pi, so the model and
+		// `/mcp` see it - and a refused registration is not fatal: the
+		// harness talks to the server through its own MCP client, so only
+		// the native tools are missing and the rest of the startup continues.
+		// SAFETY: the runtime that runs this extension exposes
+		// registerMcpServer (verified with Pi 1.4.0); the local type
+		// definitions are older, so the call is cast.
+		const result = await honcho.initHoncho({
+			apiKey,
+			pi: pi as unknown as HonchoMcpRegistrar,
+		});
 
-		if (result) {
-			logStartup("[pi-harness] Honcho integration ready");
-			addHarnessMessage("Honcho", "initialized", "ok");
-		} else {
-			logStartup("[pi-harness] Honcho: initialization returned null");
-			addHarnessMessage("Honcho", "initialization returned no client", "err", [
-				"How to fix: Check HONCHO_API_KEY in ~/.pi-harness-runtime/keys/honcho-api-key.txt",
-				"Verify Honcho account is active at honcho.dev.",
+		if (!result || !result.status) {
+			logStartup("[pi-harness] Honcho: initialization produced no status");
+			addHarnessMessage("Honcho", "init failed", "err", [
+				"Check /tmp/pi-harness.log for the Honcho reason.",
+				"The Honcho integration returned no status.",
+				"Honcho memory stays disabled for this session.",
 			]);
+			return;
+		}
+
+		switch (result.status) {
+			case "ready": {
+				logStartup("[pi-harness] Honcho integration ready");
+				if (result.mcpRegistered) {
+					logStartup("[pi-harness] Honcho: native MCP server registered");
+					addHarnessMessage("Honcho", "initialized", "ok");
+				} else {
+					// The memory works, but the model has no Honcho tools: the
+					// user has to know that, not only the log. The reason of
+					// the registration names the cause, so the advice is not
+					// always "check the Pi version".
+					const cause = honcho.redactHonchoKey(
+						result.mcpRegistrationReason ?? "the reason was not reported",
+						apiKey,
+					);
+					logStartup(`[pi-harness] Honcho: native MCP server not registered (the model sees no Honcho tools): ${cause}`);
+					// The advice follows the cause: a runtime without
+					// registerMcpServer is a different problem than a name
+					// that another extension owns.
+					const capability = cause.includes("registerMcpServer")
+						? "This runtime does not provide registerMcpServer: the Honcho memory works, but the model sees no Honcho tools."
+						: "The Honcho memory works, but the model sees no Honcho tools.";
+					addHarnessMessage("Honcho", "native MCP tools not registered", "warn", [
+						`The registration failed: ${cause}`,
+						"Check /tmp/pi-harness.log for the Honcho reason.",
+						capability,
+					]);
+				}
+				break;
+			}
+			case "missing_key": {
+				// The only state that may point at the key file: the credential
+				// is what is missing.
+				logStartup("[pi-harness] Honcho not configured:");
+				logStartup("[pi-harness]   Get key: https://app.honcho.dev/api-keys");
+				logStartup(`[pi-harness]   Then: echo "{api-key}" > ~/.pi-harness-runtime/keys/honcho-api-key.txt`);
+				addHarnessMessage("Honcho", "API key missing", "warn", [
+					...keyFileFixesOrFallback("Honcho", ["API key"]),
+					"Get a key: https://app.honcho.dev/api-keys",
+					"Then reload Pi.",
+				]);
+				break;
+			}
+			case "mcp_unavailable": {
+				// The key was read successfully - the problem is the MCP runtime.
+				const reason = honcho.redactHonchoKey(result.reason ?? "no reason given", apiKey);
+				const hint = honcho.redactHonchoKey(
+					result.hint ?? "The native MCP client library @earendil-works/pi-mcp is required.",
+					apiKey,
+				);
+				logStartup(`[pi-harness] Honcho: native MCP unavailable (${reason})`);
+				addHarnessMessage("Honcho", "native MCP unavailable", "err", [
+					"Check /tmp/pi-harness.log for the Honcho reason.",
+					reason,
+					hint,
+				]);
+				break;
+			}
+			case "registration_rejected": {
+				const reason = honcho.redactHonchoKey(
+					result.reason ?? "the server did not accept the request",
+					apiKey,
+				);
+				const httpStatus = typeof result.httpStatus === "number" ? ` (HTTP ${result.httpStatus})` : "";
+				const hint = honcho.redactHonchoKey(
+					result.hint ?? "Check the Honcho account at https://honcho.dev.",
+					apiKey,
+				);
+				logStartup(`[pi-harness] Honcho: the server refused the request${httpStatus} (the MCP server is not registered): ${reason}`);
+				addHarnessMessage("Honcho", "server refused the request", "err", [
+					"Check the Honcho account and the endpoint: https://app.honcho.dev/api-keys",
+					reason,
+					hint,
+				]);
+				break;
+			}
+			default: {
+				const reason = honcho.redactHonchoKey(String(result.status), apiKey);
+				logStartup("[pi-harness] Honcho: initialization failed:", reason);
+				addHarnessMessage("Honcho", "init failed", "err", [
+					"Check /tmp/pi-harness.log for the Honcho reason.",
+					reason,
+					"Honcho memory stays disabled for this session.",
+				]);
+				break;
+			}
 		}
 	} catch (err) {
-		logStartup("[pi-harness] Honcho: init failed:", err instanceof Error ? err.message : String(err));
+		const message = err instanceof Error ? err.message : String(err);
+		const reason =
+			honcho && typeof honcho.redactHonchoKey === "function"
+				? honcho.redactHonchoKey(message, apiKey)
+				: message;
+		logStartup("[pi-harness] Honcho: init failed:", reason);
 		addHarnessMessage("Honcho", "init failed", "err", [
-			err instanceof Error ? err.message : String(err),
-			"Check keys/honcho-api-key.txt",
+			"Check /tmp/pi-harness.log for the Honcho reason.",
+			reason,
+			"Honcho memory stays disabled for this session.",
 		]);
 	}
 }
@@ -3820,8 +4171,31 @@ async function initHermesSkills(pi: ExtensionAPI): Promise<void> {
 	addHarnessMessage("Skills", "initializing", "wait");
 	try {
 		// Dynamically import to avoid circular deps
-		const { initSkills, sanitizationStatus } =
+		const { initSkills, sanitizationStatus, sanitizationFilePath } =
 			await import("./packages/skills/dist/index.js");
+		let sanitizationFileCreated = false;
+		let sanitizationFileCreateError: string | undefined;
+		try {
+			const path = sanitizationFilePath();
+			const { existsSync, mkdirSync, writeFileSync } = await import("node:fs");
+			const { dirname } = await import("node:path");
+			if (!existsSync(path)) {
+				mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+				try {
+					writeFileSync(
+						path,
+						`${JSON.stringify({ rules: [], nameMap: {} }, null, 2)}\n`,
+						{ encoding: "utf8", flag: "wx", mode: 0o600 },
+					);
+					sanitizationFileCreated = true;
+				} catch (error) {
+					// Another Pi process may have created the file after existsSync.
+					if ((error as NodeJS.ErrnoException)?.code !== "EEXIST") throw error;
+				}
+			}
+		} catch (error) {
+			sanitizationFileCreateError = error instanceof Error ? error.message : String(error);
+		}
 
 		// Scan skills from default locations
 		const result = initSkills();
@@ -3833,21 +4207,30 @@ async function initHermesSkills(pi: ExtensionAPI): Promise<void> {
 		const local = localSkillsReport(localCount);
 		addHarnessMessage("Skills", local.text, local.status, local.details);
 		// The rules that keep a client name out of the shared collection
-		// live in a local file - they are not in the repository, it is
-		// public. Without them only the generic rules hold, and a client
-		// name travels into the collection. That is a visible state, not
-		// a silent one.
+		// live in a local file. Create a private empty template on first
+		// use; client-specific rules can be added locally.
 		try {
 			const rules = sanitizationStatus();
-			if (!rules.configured) {
+			if (sanitizationFileCreated && rules.configured) {
+				addHarnessMessage(
+					"Skill privacy",
+					"created a private sanitization rules file",
+					"info",
+					[
+						`File: ${rules.path}`,
+						"The file starts with no client-specific rules. Add private rules before publishing skills that contain client names.",
+					],
+				);
+			} else if (!rules.configured) {
 				addHarnessMessage(
 					"Skill privacy",
-					"sanitization rules not configured",
+					"sanitization rules file could not be created",
 					"warn",
 					[
-						`How to fix: create ${rules.path} with the rules of your client names, or set PI_SKILL_SANITIZATION_FILE to a file that holds them.`,
-						"The rules are not in the repository - it is public, and a list of client names in it is a list of client names in the world.",
-						"A client name can travel into the shared collection until they are.",
+						`Create ${rules.path} with { "rules": [], "nameMap": {} } and add private client-specific rules if needed.`,
+						"Check the path in PI_SKILL_SANITIZATION_FILE.",
+						"PI_SKILL_SANITIZATION_FILE must name a file path, not a JSON array.",
+						...(sanitizationFileCreateError ? [sanitizationFileCreateError] : []),
 						...(rules.error ? [rules.error] : []),
 					],
 				);
@@ -6020,6 +6403,7 @@ Run \`bd ready\` to see current bd issues.
 	// --- /usage today — focused view -------------------------------------
 	pi.registerCommand("usage-today", {
 		description: "Show today's usage + 5h window",
+		// The handler returns a Promise: the command API of Pi requires one.
 		handler: async (_args: string, ctx: ExtensionCommandContext) => {
 			const local = aggregateWindows(tracker.all());
 			const lines = [