pi-orchestrator-config 4.4.1 → 4.5.0

package/README.md

@@ -886,7 +886,7 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for tips on testing extensions locally, run
 
 ## Prerequisites
 
-- [pi](https://github.com/badlogic/pi-mono) (minimum version: **0.84.4**). Pidash uses Pi's `ui_prompt_start` and `ui_prompt_end` events to show prompt wait separately from agent work.
+- [pi](https://github.com/badlogic/pi-mono) (minimum version: **0.87.0**). Pidash uses Pi's `ui_prompt_start` and `ui_prompt_end` events to show prompt wait separately from agent work.
 - `gh` CLI (for GitHub operations)
 - `uv` (for Python execution)
 - `myk-pi-tools` (optional, for `/pr-review` and `/release`)

package/extensions/coms/coms-p2p.ts

@@ -848,10 +848,11 @@ export default function (pi: ExtensionAPI) {
 		ackOk(socket, env.msg_id);
 	}
 
-	function buildAgentCard(): AgentCard {
+	async function buildAgentCard(): Promise<AgentCard> {
 		const ctx = currentCtx;
 		const ident = identity;
 		const pct = ctx ? Math.round(ctx.getContextUsage()?.percent ?? 0) : 0;
+		log.debug("build_agent_card", { hasIdentity: !!ident });
 		return {
 			name: ident?.name ?? "unknown",
 			purpose: ident?.purpose ?? "",
@@ -859,22 +860,24 @@ export default function (pi: ExtensionAPI) {
 			color: ident?.color ?? "#36F9F6",
 			context_used_pct: pct,
 			queue_depth: getPendingInboundCount(),
-			tasks_summary: readTaskSummary(currentCtx?.cwd ?? process.cwd(), currentCtx?.sessionManager?.getSessionId?.()),
+			tasks_summary: await readTaskSummary(currentCtx?.cwd ?? process.cwd(), currentCtx?.sessionManager?.getSessionId?.()),
 		};
 	}
 
 	/** Push current agent card to ping worker so it can respond independently */
-	function updatePingWorkerCard(): void {
+	async function updatePingWorkerCard(): Promise<void> {
+		log.debug("update_ping_worker_card", { ready: pingWorkerReady });
 		if (!pingWorker || !pingWorkerReady) return;
 		try {
-			const card = buildAgentCard();
+			const card = await buildAgentCard();
 			const pong: Pong = { type: "pong", msg_id: "", agent_card: card };
 			pingWorker.postMessage({ type: "update_card", pong });
 		} catch { /* ignore */ }
 	}
 
-	function handlePing(socket: net.Socket, env: PingEnvelope): void {
-		const card = buildAgentCard();
+	async function handlePing(socket: net.Socket, env: PingEnvelope): Promise<void> {
+		log.debug("handle_ping", { msgId: env.msg_id });
+		const card = await buildAgentCard();
 		const pong: Pong = { type: "pong", msg_id: env.msg_id, agent_card: card };
 		try {
 			socket.write(JSON.stringify(pong) + "\n");
@@ -883,7 +886,7 @@ export default function (pi: ExtensionAPI) {
 		}
 		try { socket.end(); } catch { /* ignore */ }
 		// Also update worker with latest card
-		updatePingWorkerCard();
+		await updatePingWorkerCard();
 	}
 
 	function isValidEnvelope(obj: any): obj is Envelope {
@@ -935,7 +938,7 @@ export default function (pi: ExtensionAPI) {
 				} else if (parsed.type === "response") {
 					handleResponse(socket, parsed as ResponseEnvelope);
 				} else if (parsed.type === "ping") {
-					handlePing(socket, parsed as PingEnvelope);
+					void handlePing(socket, parsed as PingEnvelope).catch(() => nack(socket, parsed.msg_id, "internal error"));
 				} else if (parsed.type === "task_update") {
 					handleTaskUpdate(socket, parsed as TaskUpdateEnvelope);
 				} else if (parsed.type === "queue_manage") {
@@ -1994,7 +1997,7 @@ Do not respond to this message.`;
 			// Append sender's active tasks for this peer to the prompt
 			let promptText = params.prompt;
 			try {
-				const { listTasksForSession } = require("../pitasks/index.js");
+				const { listTasksForSession } = await import("../pitasks/index.js");
 				const targetPiSessionId = target.pi_session_id || target.coms_session_id;
 				const allTasks = listTasksForSession(targetPiSessionId, target.cwd) || [];
 				const myTasks = allTasks.filter((t: any) =>
@@ -2021,27 +2024,8 @@ Do not respond to this message.`;
 				tasks: params.tasks ?? null,
 			};
 
-			// Send the envelope synchronously and wait for the receiver's ack.
-			await sendEnvelope(target.endpoint, env);
-			comsSendCalledThisTurn.add(target.coms_session_id);
-
-			// Auto-create tasks on the target's task store (sender-side, instant)
-			if (params.tasks && params.tasks.length > 0 && target.coms_session_id) {
-				try {
-					const count = createComsInboundTasks(
-						params.tasks,
-						{ sender_session: identity.coms_session_id, sender_name: identity.name, sender_endpoint: identity.endpoint },
-						target.pi_session_id || target.coms_session_id,
-						target.cwd,
-					);
-					if (count > 0) {
-						log.info("tasks_auto_created", msg_id, "to", target.name, "count", count);
-					}
-				} catch { /* best-effort */ }
-			}
-
-			// Register a pending entry whose promise the receiver-side handleResponse
-			// (or the timeout below) will settle.
+			// Register before sending. A peer may acknowledge and respond before
+			// task creation's dynamic import completes.
 			let resolveFn!: (v: { response?: any; error?: string | null }) => void;
 			let rejectFn!: (e: Error) => void;
 			const promise = new Promise<{ response?: any; error?: string | null }>((res, rej) => {
@@ -2069,13 +2053,37 @@ Do not respond to this message.`;
 			try { (entry.timer as any).unref?.(); } catch { /* ignore */ }
 			pendingReplies.set(msg_id, entry);
 
-			log.debug("outbound_prompt", msg_id, "to", target.name, "hops", hops);
-
-			// Track pending outbound
 			const targetKey = target.name;
 			if (!pendingOutbound.has(targetKey)) pendingOutbound.set(targetKey, new Set());
 			pendingOutbound.get(targetKey)!.add(msg_id);
 
+			try {
+				await sendEnvelope(target.endpoint, env);
+			} catch (error) {
+				pendingReplies.delete(msg_id);
+				pendingOutbound.get(targetKey)?.delete(msg_id);
+				if (pendingOutbound.get(targetKey)?.size === 0) pendingOutbound.delete(targetKey);
+				if (entry.timer) clearTimeout(entry.timer);
+				throw error;
+			}
+			comsSendCalledThisTurn.add(target.coms_session_id);
+
+			if (params.tasks && params.tasks.length > 0 && target.coms_session_id) {
+				try {
+					const count = await createComsInboundTasks(
+						params.tasks,
+						{ sender_session: identity.coms_session_id, sender_name: identity.name, sender_endpoint: identity.endpoint },
+						target.pi_session_id || target.coms_session_id,
+						target.cwd,
+					);
+					if (count > 0) log.info("tasks_auto_created", msg_id, "to", target.name, "count", count);
+				} catch (error) {
+					log.warn("tasks_auto_create_failed", { msg_id, target: target.name, error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+
+			log.debug("outbound_prompt", msg_id, "to", target.name, "hops", hops);
+
 			// Peer status from peerCards
 			const peerCard = peerCards.get(target.coms_session_id);
 			const peer_queue_depth = peerCard?.queue_depth ?? 0;
@@ -2305,6 +2313,7 @@ Do not respond to this message.`;
 			}), { description: "Tasks to create on the peer" }),
 		}),
 		async execute(_callId, params) {
+			log.debug("coms_tasks_create_start", { target: params.target, count: params.tasks?.length ?? 0 });
 			if (!identity) throw new Error("coms not initialised");
 			if (!params.tasks || params.tasks.length === 0) throw new Error("coms_tasks_create requires at least one task");
 			const target = await resolveTarget(params.target);
@@ -2320,7 +2329,7 @@ Do not respond to this message.`;
 			if (identity.endpoint) meta.sender_endpoint = identity.endpoint;
 
 			try {
-				const { createTasksForSession, listTasksForSession, updateTaskForSession } = require("../pitasks/index.js");
+				const { createTasksForSession, listTasksForSession, updateTaskForSession } = await import("../pitasks/index.js");
 				const targetPiSessionId = target.pi_session_id || target.coms_session_id;
 
 				// Create all tasks in one batch
@@ -2401,12 +2410,13 @@ Do not respond to this message.`;
 			task_id: Type.String({ description: "Task ID to delete." }),
 		}),
 		async execute(_callId, params) {
+			log.debug("coms_task_delete_start", { target: params.target, taskId: params.task_id });
 			if (!identity) throw new Error("coms not initialised");
 			const target = await resolveTarget(params.target);
 			if (!target) throw new Error(`coms: no live agent matching "${params.target}"`);
 
 			try {
-				const { getTaskForSession, deleteTaskForSession } = require("../pitasks/index.js");
+				const { getTaskForSession, deleteTaskForSession } = await import("../pitasks/index.js");
 				const targetPiSessionId = target.pi_session_id || target.coms_session_id;
 				const task = getTaskForSession(targetPiSessionId, params.task_id, target.cwd);
 				if (!task) throw new Error(`Task #${params.task_id} not found`);
@@ -2440,12 +2450,13 @@ Do not respond to this message.`;
 			target: Type.String({ description: "Peer name or session_id." }),
 		}),
 		async execute(_callId, params) {
+			log.debug("coms_task_list_start", { target: params.target });
 			if (!identity) throw new Error("coms not initialised");
 			const target = await resolveTarget(params.target);
 			if (!target) throw new Error(`coms: no live agent matching "${params.target}"`);
 
 			try {
-				const { listTasksForSession } = require("../pitasks/index.js");
+				const { listTasksForSession } = await import("../pitasks/index.js");
 				const targetPiSessionId = target.pi_session_id || target.coms_session_id;
 				const tasks = listTasksForSession(targetPiSessionId, target.cwd);
 				log.debug("coms_task_list", target.name, "tasks", tasks?.length ?? 0);
@@ -2494,12 +2505,13 @@ Do not respond to this message.`;
 			task_id: Type.String({ description: "Task ID to retrieve." }),
 		}),
 		async execute(_callId, params) {
+			log.debug("coms_task_get_start", { target: params.target, taskId: params.task_id });
 			if (!identity) throw new Error("coms not initialised");
 			const target = await resolveTarget(params.target);
 			if (!target) throw new Error(`coms: no live agent matching "${params.target}"`);
 
 			try {
-				const { getTaskForSession } = require("../pitasks/index.js");
+				const { getTaskForSession, listTasksForSession } = await import("../pitasks/index.js");
 				const targetPiSessionId = target.pi_session_id || target.coms_session_id;
 				const task = getTaskForSession(targetPiSessionId, params.task_id, target.cwd);
 				if (!task) throw new Error(`Task #${params.task_id} not found on ${target.name}`);
@@ -2512,7 +2524,6 @@ Do not respond to this message.`;
 				if (task.owner) lines.push(`Owner: ${task.owner}`);
 				lines.push(`Description: ${desc}`);
 				if (task.blockedBy?.length > 0) {
-					const { listTasksForSession } = require("../pitasks/index.js");
 					const allTasks = listTasksForSession(targetPiSessionId, target.cwd);
 					const openBlockers = task.blockedBy.filter((bid: string) => {
 						const blocker = allTasks.find((bt: any) => bt.id === bid);
@@ -2549,12 +2560,13 @@ Do not respond to this message.`;
 			addBlockedBy: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that block this task" })),
 		}),
 		async execute(_callId, params) {
+			log.debug("coms_task_update_start", { target: params.target, taskId: params.task_id });
 			if (!identity) throw new Error("coms not initialised");
 			const target = await resolveTarget(params.target);
 			if (!target) throw new Error(`coms: no live agent matching "${params.target}"`);
 
 			try {
-				const { getTaskForSession, updateTaskForSession } = require("../pitasks/index.js");
+				const { getTaskForSession, updateTaskForSession } = await import("../pitasks/index.js");
 				const targetPiSessionId = target.pi_session_id || target.coms_session_id;
 				const task = getTaskForSession(targetPiSessionId, params.task_id, target.cwd);
 				if (!task) throw new Error(`Task #${params.task_id} not found on ${target.name}`);

package/extensions/coms/coms-shared.ts

@@ -461,9 +461,10 @@ export function readFrontmatterFromArgv(argv: string[]): { name?: string; descri
 	}
 }
 
-export function readTaskSummary(_cwd: string, _sessionId?: string): { total: number; completed: number; in_progress: number } | null {
+export async function readTaskSummary(_cwd: string, _sessionId?: string): Promise<{ total: number; completed: number; in_progress: number } | null> {
+	log.debug("read_task_summary", { hasSessionId: !!_sessionId });
 	try {
-		const { listTasks } = require("../pitasks/index.js");
+		const { listTasks } = await import("../pitasks/index.js");
 		const tasks = listTasks();
 		if (!tasks || tasks.length === 0) return null;
 		let total = 0, completed = 0, in_progress = 0;
@@ -650,17 +651,18 @@ const MAX_TASK_FIELD_LEN = 2000;
  * Runs on the SENDER side — uses createTaskForSession with the target's session ID.
  * TaskStore handles locking, file format, everything.
  */
-export function createComsInboundTasks(
+export async function createComsInboundTasks(
 	tasks: Array<{ subject: string; description: string }>,
 	origin: ComsOrigin,
 	targetSessionId: string,
 	targetCwd?: string,
-): number {
+): Promise<number> {
+	log.debug("create_coms_inbound_tasks", { targetSessionId, count: tasks?.length ?? 0 });
 	if (!tasks || tasks.length === 0 || !targetSessionId) return 0;
 
 	let createTaskForSession: any;
 	try {
-		createTaskForSession = require("../pitasks/index.js").createTaskForSession;
+		createTaskForSession = (await import("../pitasks/index.js")).createTaskForSession;
 	} catch { return 0; }
 	if (!createTaskForSession) return 0;
 

package/extensions/orchestrator/agents.ts

@@ -9,7 +9,13 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { createLogger } from "../shared/logger.js";
+
+const log = createLogger("agents");
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -103,7 +109,9 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
  * and the agents are in ../../agents/ relative to this file.
  */
 function getPackageAgentsDir(): string {
-	return path.resolve(__dirname, "..", "..", "agents");
+	const resolvedPath = path.resolve(MODULE_DIR, "..", "..", "agents");
+	log.debug("resolved package agents directory", { path: resolvedPath });
+	return resolvedPath;
 }
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {

package/extensions/orchestrator/project-settings.ts

@@ -19,12 +19,17 @@
  */
 
 import { existsSync, statSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import { homedir } from "node:os";
 import stripJsonComments from "strip-json-comments";
 import { resolveRepoRoot } from "./utils.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  findSettingsFile,
+  SETTINGS_FILENAMES,
+  SETTINGS_KEYS,
+  type SettingsKeyDef,
+} from "./settings-source.js";
 
 interface ProjectSettings {
   commit_trailer?: boolean | string;
@@ -97,33 +102,8 @@ interface ProjectSettings {
   pidiff_daemon_startup_timeout_s?: number;
 }
 
-/** Key definition from settings-keys.json — single source of truth for env names + defaults. */
-export interface SettingsKeyDef {
-  description: string;
-  type: string;
-  env?: string;
-  default: unknown;
-  min?: number;
-  max?: number;
-  strict_digits?: boolean;
-  per_key_resolution?: boolean;
-  enum?: string[];
-}
-
-const SETTINGS_FILENAMES = ["pi-config-settings.jsonc", "pi-config-settings.json"];
-
-/** Find the first existing settings file in a directory (.jsonc preferred over .json). */
-export function findSettingsFile(dir: string): string | null {
-  for (const name of SETTINGS_FILENAMES) {
-    const p = join(dir, name);
-    if (existsSync(p)) return p;
-  }
-  return null;
-}
-
-export const SETTINGS_KEYS: Record<string, SettingsKeyDef> = JSON.parse(
-  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "settings-keys.json"), "utf-8"),
-);
+/** Settings metadata is loaded from settings-keys.json by the cycle-free settings source. */
+export { findSettingsFile, SETTINGS_KEYS, type SettingsKeyDef };
 
 /** Dev-time check: every ProjectSettings field must have a JSON definition. */
 const PROJECT_SETTINGS_KEYS: (keyof ProjectSettings)[] = [

package/extensions/orchestrator/rules.ts

@@ -12,6 +12,7 @@ const log = createLogger("rules");
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatDuration } from "./async-agents.js";
 import { buildSituationReport, estimateMemoryBudget, rebuildAndOrganize } from "./situation-report.js";
@@ -22,6 +23,8 @@ import { isComsActive } from "../shared/coms-active.js";
 import { JsonlAppendLog } from "./state-jsonl.js";
 import { getProjectDataDir } from "./utils.js";
 
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
 /** Per-cwd telemetry log cache — avoids re-creating on every call. */
 const telemetryLogCache = new Map<string, JsonlAppendLog<Record<string, unknown>>>();
 
@@ -131,7 +134,7 @@ export function registerRules(
     // Load from: package rules/ → user ~/.pi/agent/rules/ → project .pi/rules/
     // Same-filename override: project > user > package
     if (!isSubagent) {
-      const packageRulesDir = path.resolve(__dirname, "..", "..", "rules");
+      const packageRulesDir = path.resolve(MODULE_DIR, "..", "..", "rules");
       const userRulesDir = path.join(os.homedir(), ".pi", "agent", "rules");
       const projectRulesDir = path.join(ctx.cwd, ".pi", "rules");
 

package/extensions/orchestrator/session-validation.ts

@@ -6,10 +6,16 @@ import { execSync, execFileSync } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { setUvAvailable, isUvAvailable } from "./enforcement-helpers.js";
 import { registerMcpc } from "./mcpc.js";
 import { checkMinPiVersion } from "./utils.js";
+import { createLogger } from "../shared/logger.js";
+
+const log = createLogger("session-validation");
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
 /** Check whether a CLI command is available on PATH. */
 function hasCmd(cmd: string): boolean {
@@ -240,7 +246,9 @@ async function checkSessionTools(ctx: any): Promise<void> {
         "prek — pre-commit wrapper (.pre-commit-config.yaml detected). Install: https://github.com/j178/prek",
       );
     }
-  } catch (e: any) { console.debug("[session-validation] tool detection failed:", e?.message || e); }
+  } catch (error) {
+    log.warn("tool detection failed", { cwd: ctx.cwd, operation: "checkSessionTools", error: error instanceof Error ? error.message : String(error) });
+  }
 
   if (missing.length > 0 || optional.length > 0) {
     const parts: string[] = [];
@@ -259,26 +267,29 @@ async function checkSessionTools(ctx: any): Promise<void> {
   }
 }
 
+export function findPackageVersion(startDir = MODULE_DIR): string | null {
+  let searchDir = startDir;
+  for (let i = 0; i < 5; i++) {
+    const candidate = path.join(searchDir, "package.json");
+    if (fs.existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+        if (pkg.name === "pi-orchestrator-config" && pkg.version) return pkg.version;
+      } catch (error) {
+        log.warn("package manifest read or parse failed", { path: candidate, operation: "findPackageVersion", error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    searchDir = path.dirname(searchDir);
+  }
+  return null;
+}
+
 /** Check for pi-config version upgrades and show changelog notification. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 async function checkUpgradeChangelog(ctx: any): Promise<void> {
-  // Find pi-config package.json by walking up from this file's directory
+  log.debug("checking upgrade changelog", { operation: "checkUpgradeChangelog" });
   try {
-    let searchDir = __dirname ?? path.dirname(new URL(import.meta.url).pathname);
-    let currentVersion: string | null = null;
-    for (let i = 0; i < 5; i++) {
-      const candidate = path.join(searchDir, "package.json");
-      if (fs.existsSync(candidate)) {
-        try {
-          const pkg = JSON.parse(fs.readFileSync(candidate, "utf-8"));
-          if (pkg.name === "pi-orchestrator-config" && pkg.version) {
-            currentVersion = pkg.version;
-            break;
-          }
-        } catch (e: any) { console.debug("[session-validation] package.json parse failed:", e?.message || e); }
-      }
-      searchDir = path.dirname(searchDir);
-    }
+    const currentVersion = findPackageVersion();
     if (currentVersion) {
       const versionFile = path.join(
         process.env.HOME || "",
@@ -288,14 +299,18 @@ async function checkUpgradeChangelog(ctx: any): Promise<void> {
       let lastVersion: string | null = null;
       try {
         lastVersion = fs.readFileSync(versionFile, "utf-8").trim();
-      } catch (e: any) { console.debug("[session-validation] read last version failed:", e?.message || e); }
+      } catch (error) {
+        log.debug("last version read failed", { path: versionFile, operation: "read", error: error instanceof Error ? error.message : String(error) });
+      }
 
       if (!lastVersion) {
         // First run — just record the version, no notification
         try {
           fs.mkdirSync(path.dirname(versionFile), { recursive: true });
           fs.writeFileSync(versionFile, currentVersion, "utf-8");
-        } catch (e: any) { console.debug("[session-validation] write version file failed:", e?.message || e); }
+        } catch (error) {
+          log.warn("version file write failed", { path: versionFile, operation: "initial-write", error: error instanceof Error ? error.message : String(error) });
+        }
       } else if (lastVersion !== currentVersion && hasCmd("gh")) {
         // Version changed — fetch release notes (5s timeout, no shell)
         const tag = `v${currentVersion}`;
@@ -318,18 +333,24 @@ async function checkUpgradeChangelog(ctx: any): Promise<void> {
             );
             notified = true;
           }
-        } catch (e: any) { console.debug("[session-validation] release notes fetch failed:", e?.message || e); }
+        } catch (error) {
+          log.warn("release notes fetch failed", { tag, operation: "fetch", error: error instanceof Error ? error.message : String(error) });
+        }
         // Only update version file after successful notification
         // so failed attempts retry on next session
         if (notified) {
           try {
             fs.mkdirSync(path.dirname(versionFile), { recursive: true });
             fs.writeFileSync(versionFile, currentVersion, "utf-8");
-          } catch (e: any) { console.debug("[session-validation] write version after notify failed:", e?.message || e); }
+          } catch (error) {
+            log.warn("version file write failed", { path: versionFile, operation: "post-notify-write", error: error instanceof Error ? error.message : String(error) });
+          }
         }
       }
     }
-  } catch (e: any) { console.debug("[session-validation] upgrade changelog failed:", e?.message || e); }
+  } catch (error) {
+    log.warn("upgrade changelog check failed", { operation: "checkUpgradeChangelog", error: error instanceof Error ? error.message : String(error) });
+  }
 }
 
 export function registerSessionValidation(pi: ExtensionAPI): void {
@@ -342,8 +363,8 @@ export function registerSessionValidation(pi: ExtensionAPI): void {
     try {
       const uvInstalled = hasCmd("uv");
       setUvAvailable(uvInstalled);
-    } catch (e: any) {
-      console.debug("[session-validation] uv check failed:", e?.message || e);
+    } catch (error) {
+      log.warn("uv availability check failed", { operation: "session_start", error: error instanceof Error ? error.message : String(error) });
     }
 
     if (!ctx.hasUI) return;

package/extensions/orchestrator/settings-source.ts

@@ -0,0 +1,139 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import stripJsonComments from "strip-json-comments";
+
+let log: { debug(message: string, context?: object): void; warn(message: string, context?: object): void } = {
+  debug: () => {}, warn: () => {},
+};
+export function setSettingsSourceLogger(logger: typeof log): void {
+  log = logger;
+}
+
+export interface SettingsKeyDef {
+  description: string;
+  type: string;
+  env?: string;
+  default: unknown;
+  min?: number;
+  max?: number;
+  strict_digits?: boolean;
+  per_key_resolution?: boolean;
+  enum?: string[];
+}
+
+export const SETTINGS_FILENAMES = ["pi-config-settings.jsonc", "pi-config-settings.json"];
+
+export const SETTINGS_KEYS: Record<string, SettingsKeyDef> = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "settings-keys.json"), "utf8"),
+);
+
+export function findSettingsFile(dir: string): string | null {
+  for (const name of SETTINGS_FILENAMES) {
+    const file = join(dir, name);
+    if (existsSync(file)) {
+      log.debug("found settings file", { path: file });
+      return file;
+    }
+  }
+  log.debug("settings file not found", { path: dir });
+  return null;
+}
+
+export function readSettingsObject(file: string | null, key?: string): Record<string, unknown> {
+  if (!file) {
+    log.debug("settings read skipped", { path: null, key });
+    return {};
+  }
+  try {
+    const value = JSON.parse(stripJsonComments(readFileSync(file, "utf8")));
+    log.debug("settings read", { path: file, key, validObject: Boolean(value && typeof value === "object" && !Array.isArray(value)) });
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  } catch (error) {
+    log.warn("settings read or parse failed", { path: file, key, error: error instanceof Error ? error.message : String(error) });
+    return {};
+  }
+}
+
+const repoRootCache = new Map<string, string>();
+let repoRootResolver = resolveRepoRootUncached;
+
+export function setRepoRootResolverForTests(resolver: (cwd: string) => string): void {
+  repoRootResolver = resolver;
+  repoRootCache.clear();
+}
+
+function resolveRepoRoot(cwd: string): string {
+  const resolvedCwd = resolve(cwd);
+  const cached = repoRootCache.get(resolvedCwd);
+  if (cached) return cached;
+  const root = repoRootResolver(resolvedCwd);
+  repoRootCache.set(resolvedCwd, root);
+  return root;
+}
+
+function resolveRepoRootUncached(cwd: string): string {
+  try {
+    const common = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const root = dirname(resolve(cwd, common));
+    log.debug("resolved standalone settings repository root", { cwd, root });
+    return root;
+  } catch (error) {
+    let current = resolve(cwd);
+    while (true) {
+      const dotGit = join(current, ".git");
+      if (existsSync(dotGit)) {
+        if (statSync(dotGit).isDirectory()) return current;
+        const match = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf8"));
+        if (match) {
+          const gitDir = resolve(current, match[1].trim());
+          const commonFile = join(gitDir, "commondir");
+          if (existsSync(commonFile)) {
+            const root = dirname(resolve(gitDir, readFileSync(commonFile, "utf8").trim()));
+            log.debug("resolved standalone worktree repository root", { cwd, root });
+            return root;
+          }
+        }
+        return current;
+      }
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+    log.debug("standalone settings repository root fallback", { cwd, error: error instanceof Error ? error.message : String(error) });
+    return cwd;
+  }
+}
+
+function isValidCandidate(value: unknown, definition: SettingsKeyDef | undefined): boolean {
+  if (!definition) return false;
+  const typeValid = definition.type === "string" ? typeof value === "string"
+    : definition.type === "bool" ? typeof value === "boolean"
+    : definition.type === "int" ? Number.isInteger(value)
+    : true;
+  const valid = typeValid && (!definition.enum || definition.enum.includes(value as string));
+  log.debug("validated standalone setting candidate", { type: definition.type, hasEnum: Boolean(definition.enum), valid });
+  return valid;
+}
+
+export function getStandaloneSetting(cwd: string, key: string): unknown {
+  const definition = SETTINGS_KEYS[key];
+  const root = resolveRepoRoot(cwd);
+  for (const [source, file] of [
+    ["project", findSettingsFile(join(root, ".pi"))],
+    ["global", findSettingsFile(join(process.env.HOME || homedir(), ".pi"))],
+  ] as const) {
+    const settings = readSettingsObject(file, key);
+    if (key in settings && isValidCandidate(settings[key], definition)) {
+      log.debug("resolved standalone setting", { key, source, path: file });
+      return settings[key];
+    }
+  }
+  const fromEnv = definition?.env && process.env[definition.env] !== undefined;
+  log.debug("resolved standalone setting fallback", { key, source: fromEnv ? "environment" : "default" });
+  return fromEnv ? process.env[definition!.env!] : definition?.default;
+}

package/extensions/orchestrator/utils.ts

@@ -148,7 +148,7 @@ export function tryGetSystemPromptOptions(ctx: any): { contextFiles?: any[]; ski
 }
 
 /** Minimum pi version required by this pi-config version. */
-export const MIN_PI_VERSION = "0.84.4";
+export const MIN_PI_VERSION = "0.87.0";
 
 /** Get the installed pi version from its package.json. */
 export function getPiVersion(): string | null {