pi-orchestrator-config 4.2.0 → 4.3.2

package/extensions/orchestrator/project-settings.ts

@@ -1,12 +1,14 @@
 /**
- * Project-level settings — loads .pi/pi-config-settings.json with env var fallback.
+ * Project-level settings — loads .pi/pi-config-settings.jsonc (or .json) with env var fallback.
  *
  * Resolution order:
- * 1. Project .pi/pi-config-settings.json (wins if set)
- * 2. Global ~/.pi/pi-config-settings.json (fallback for all projects)
+ * 1. Project .pi/pi-config-settings.jsonc or .json (wins if set, .jsonc preferred)
+ * 2. Global ~/.pi/pi-config-settings.jsonc or .json (fallback for all projects)
  * 3. Env var (PI_COMMIT_TRAILER, PI_USE_WORKTREES, PI_DREAM_INTERVAL_HOURS, PI_DCO,
  *    ACPX_AGENTS, CLI_AGENTS, PI_PIDASH_ENABLE, PI_PIDIFF_ENABLE, PI_PIDASH_PORT, PI_IMAGE_MODEL,
- *    PI_ASYNC_LLM_PROVIDER, PI_ASYNC_LLM_MODEL, PI_REVIEW_LOOP_MAX_CYCLES)
+ *    PI_INTERNAL_OPERATIONS_PROVIDER, PI_INTERNAL_OPERATIONS_MODEL, PI_REVIEW_LOOP_MAX_CYCLES,
+ *    PI_ENFORCEMENT_ALLOWED_COMMANDS, VERTEX_CLAUDE_1M, PI_SIDECAR_LOG_LEVEL,
+ *    PI_COMS_MAX_HOPS, PI_COMS_TIMEOUT_MS, PI_COMS_DIR)
  * 4. Default (dream_interval_hours defaults to 3; acpx_agents/cli_agents to []; pidash_enable/pidiff_enable to true; pidash_port to 19190;
  *    review_loop_max_cycles to 3)
  *
@@ -17,8 +19,10 @@
  */
 
 import { existsSync, statSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 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";
 
@@ -38,11 +42,17 @@ interface ProjectSettings {
   pidash_enable?: boolean;
   pidiff_enable?: boolean;
   pidash_port?: number;
+  task_auto_clear_enabled?: boolean;
+  task_auto_clear_minutes?: number;
+  task_reminder_enabled?: boolean;
+  task_reminder_interval_minutes?: number;
+  task_stale_in_progress_enabled?: boolean;
+  task_stale_in_progress_minutes?: number;
   image_model?: string;
   /** Provider for detached LLM async children when parent is acpx (must-async / dream). */
-  async_llm_provider?: string;
+  internal_operations_provider?: string;
   /** Model id for detached LLM async children when parent is acpx. */
-  async_llm_model?: string;
+  internal_operations_model?: string;
   /** Max review-loop cycles injected into the rules prompt. Integer 1-10 only. */
   review_loop_max_cycles?: number;
   /** Default provider for all subagents. */
@@ -51,18 +61,127 @@ interface ProjectSettings {
   agent_model?: string;
   /** Per-agent provider/model overrides. null = use parent model (skip global agent_provider/agent_model). */
   agent_overrides?: Record<string, { provider?: string | null; model?: string | null }>;
+  /** Enable 1M context window variants for Vertex Claude models. */
+  vertex_claude_1m?: boolean;
+  /** Log level for pi-sidecar (debug, info, warn, error). */
+  sidecar_log_level?: string;
+  /** Colon-separated command allowlist for enforcement. Empty = allow all. */
+  enforcement_allowed_commands?: string;
+  /** Enforcement: max sleep seconds allowed in loop context. */
+  enforcement_loop_sleep_threshold_s?: number;
+  /** Enforcement: max sleep seconds allowed standalone. */
+  enforcement_sleep_threshold_s?: number;
+  /** Subagent: max sync agent duration in seconds. */
+  sync_agent_max_seconds?: number;
+  /** Subagent: async poller interval in ms. */
+  async_poll_interval_ms?: number;
+  /** Subagent: async phantom timeout in ms. */
+  async_phantom_timeout_ms?: number;
+  /** Max hops for P2P coms message relay. */
+  coms_max_hops?: number;
+  /** P2P coms message response timeout in ms. */
+  coms_timeout_ms?: number;
+  /** P2P coms data directory. Empty = ~/.pi/coms. */
+  coms_dir?: string;
+  /** Coms task heartbeat interval in ms. */
+  coms_task_heartbeat_ms?: number;
+  /** Coms: entry grace period in ms. */
+  coms_entry_grace_period_ms?: number;
+  /** Coms: probe timeout in ms. */
+  coms_probe_timeout_ms?: number;
+  /** Pidiff: stale lock timeout in ms. */
+  pidiff_stale_lock_timeout_ms?: number;
+  /** Pidiff: daemon startup timeout in seconds. */
+  pidiff_daemon_startup_timeout_s?: number;
 }
 
-const SETTINGS_FILENAME = "pi-config-settings.json";
+/** 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;
+}
+
+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"),
+);
 
-function getSettingsPath(cwd: string): string {
-  return join(resolveRepoRoot(cwd), ".pi", SETTINGS_FILENAME);
+/** Dev-time check: every ProjectSettings field must have a JSON definition. */
+const PROJECT_SETTINGS_KEYS: (keyof ProjectSettings)[] = [
+  "commit_trailer",
+  "allow_push_to_protected_branches",
+  "use_worktrees",
+  "dream_interval_hours",
+  "dco",
+  "comment_signature",
+  "review_loop_enforcement",
+  "orchestrator_edit_write_block",
+  "acpx_agents",
+  "cli_agents",
+  "pidash_enable",
+  "pidiff_enable",
+  "pidash_port",
+  "task_auto_clear_enabled",
+  "task_auto_clear_minutes",
+  "task_reminder_enabled",
+  "task_reminder_interval_minutes",
+  "task_stale_in_progress_enabled",
+  "task_stale_in_progress_minutes",
+  "image_model",
+  "internal_operations_provider",
+  "internal_operations_model",
+  "review_loop_max_cycles",
+  "agent_provider",
+  "agent_model",
+  "agent_overrides",
+  "vertex_claude_1m",
+  "sidecar_log_level",
+  "enforcement_allowed_commands",
+  "enforcement_loop_sleep_threshold_s",
+  "enforcement_sleep_threshold_s",
+  "sync_agent_max_seconds",
+  "async_poll_interval_ms",
+  "async_phantom_timeout_ms",
+  "coms_max_hops",
+  "coms_timeout_ms",
+  "coms_dir",
+  "coms_task_heartbeat_ms",
+  "coms_entry_grace_period_ms",
+  "coms_probe_timeout_ms",
+  "pidiff_stale_lock_timeout_ms",
+  "pidiff_daemon_startup_timeout_s",
+];
+for (const key of PROJECT_SETTINGS_KEYS) {
+  if (!(key in SETTINGS_KEYS)) {
+    throw new Error(`[project-settings] settings-keys.json missing key: ${key}`);
+  }
 }
 
-function parseSettingsFile(filePath: string): ProjectSettings {
+export function getSettingsPath(cwd: string): string {
+  const piDir = join(resolveRepoRoot(cwd), ".pi");
+  return findSettingsFile(piDir) ?? join(piDir, SETTINGS_FILENAMES[0]);
+}
+
+export function parseSettingsFile(filePath: string): ProjectSettings {
   if (!existsSync(filePath)) return {};
   try {
-    const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+    const raw = JSON.parse(stripJsonComments(readFileSync(filePath, "utf-8")));
     if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {};
     const result: ProjectSettings = {};
     if (typeof raw.commit_trailer === "boolean" || typeof raw.commit_trailer === "string") result.commit_trailer = raw.commit_trailer;
@@ -83,11 +202,11 @@ function parseSettingsFile(filePath: string): ProjectSettings {
     if (typeof raw.image_model === "string" && raw.image_model.trim()) {
       result.image_model = raw.image_model.trim();
     }
-    if (typeof raw.async_llm_provider === "string" && raw.async_llm_provider.trim()) {
-      result.async_llm_provider = raw.async_llm_provider.trim();
+    if (typeof raw.internal_operations_provider === "string" && raw.internal_operations_provider.trim()) {
+      result.internal_operations_provider = raw.internal_operations_provider.trim();
     }
-    if (typeof raw.async_llm_model === "string" && raw.async_llm_model.trim()) {
-      result.async_llm_model = raw.async_llm_model.trim();
+    if (typeof raw.internal_operations_model === "string" && raw.internal_operations_model.trim()) {
+      result.internal_operations_model = raw.internal_operations_model.trim();
     }
     const parsedMaxCycles = parseReviewLoopMaxCycles(raw.review_loop_max_cycles);
     if (parsedMaxCycles !== undefined) {
@@ -115,13 +234,56 @@ function parseSettingsFile(filePath: string): ProjectSettings {
         if (typeof val === "object" && val !== null && !Array.isArray(val)) {
           const v = val as { provider?: unknown; model?: unknown };
           const entry: { provider?: string | null; model?: string | null } = {};
-          if (v.provider === null || (typeof v.provider === "string")) entry.provider = v.provider === null ? null : v.provider.trim() || undefined;
-          if (v.model === null || (typeof v.model === "string")) entry.model = v.model === null ? null : v.model.trim() || undefined;
+          if (v.provider === null) entry.provider = null;
+          else if (typeof v.provider === "string") entry.provider = v.provider.trim() || undefined;
+          if (v.model === null) entry.model = null;
+          else if (typeof v.model === "string") entry.model = v.model.trim() || undefined;
           if (entry.provider !== undefined || entry.model !== undefined) overrides[name] = entry;
         }
       }
       if (Object.keys(overrides).length > 0) result.agent_overrides = overrides;
     }
+
+    // Data-driven parsing for remaining settings — derive from settings-keys.json types
+    const SPECIAL_CASE_KEYS = new Set<string>([
+      "commit_trailer", "allow_push_to_protected_branches", "use_worktrees",
+      "dream_interval_hours", "dco", "comment_signature", "review_loop_enforcement",
+      "orchestrator_edit_write_block", "pidash_enable", "pidiff_enable", "pidash_port",
+      "image_model", "internal_operations_provider", "internal_operations_model",
+      "review_loop_max_cycles", "acpx_agents", "cli_agents", "agent_provider",
+      "agent_model", "agent_overrides",
+    ]);
+    for (const [k, def] of Object.entries(SETTINGS_KEYS)) {
+      if (SPECIAL_CASE_KEYS.has(k) || k in result) continue;
+      if (!(k in raw)) continue;
+      const val = raw[k];
+      switch (def.type) {
+        case "bool":
+          if (typeof val === "boolean") (result as any)[k] = val;
+          break;
+        case "string":
+          if (typeof val === "string") (result as any)[k] = val.trim();
+          break;
+        case "int": {
+          if (typeof val === "number" && Number.isInteger(val)) {
+            const min = def.min ?? 0;
+            const max = def.max ?? Number.MAX_SAFE_INTEGER;
+            if (val >= min && val <= max) (result as any)[k] = val;
+          }
+          break;
+        }
+        case "port": {
+          const min = def.min ?? 0;
+          if (typeof val === "number" && Number.isInteger(val) && val >= min && val <= 65535) {
+            (result as any)[k] = val;
+          }
+          break;
+        }
+        case "number":
+          if (typeof val === "number" && Number.isFinite(val)) (result as any)[k] = val;
+          break;
+      }
+    }
     return result;
   } catch (e: any) {
     console.debug(`[project-settings] failed to parse ${filePath}:`, e?.message?.slice(0, 100));
@@ -129,7 +291,7 @@ function parseSettingsFile(filePath: string): ProjectSettings {
   }
 }
 
-function loadProjectSettings(cwd: string): ProjectSettings {
+export function loadProjectSettings(cwd: string): ProjectSettings {
   return parseSettingsFile(getSettingsPath(cwd));
 }
 
@@ -142,16 +304,20 @@ export function setGlobalSettingsPath(path: string | null): void {
   clearSettingsCache();
 }
 
-function loadGlobalSettings(): ProjectSettings {
-  const globalPath = globalSettingsPathOverride ?? join(homedir(), ".pi", SETTINGS_FILENAME);
-  return parseSettingsFile(globalPath);
+/** Resolved global settings file path (honors test override). */
+export function getGlobalSettingsPath(): string {
+  return globalSettingsPathOverride ?? findSettingsFile(join(homedir(), ".pi")) ?? join(homedir(), ".pi", SETTINGS_FILENAMES[0]);
+}
+
+export function loadGlobalSettings(): ProjectSettings {
+  return parseSettingsFile(getGlobalSettingsPath());
 }
 
 function projectSettingsFileHasKey(cwd: string, key: string): boolean {
   const filePath = getSettingsPath(cwd);
   if (!existsSync(filePath)) return false;
   try {
-    const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+    const raw = JSON.parse(stripJsonComments(readFileSync(filePath, "utf-8")));
     return typeof raw === "object" && raw !== null && !Array.isArray(raw) && key in raw;
   } catch (e: any) {
     console.debug(`[project-settings] failed to check key in ${filePath}:`, e?.message?.slice(0, 100));
@@ -257,7 +423,7 @@ function getSettings(cwd: string): ProjectSettings {
       cachedMtime = existsSync(settingsPath) ? statSync(settingsPath).mtimeMs : 0;
     } catch { cachedMtime = 0; }
     try {
-      const globalPath = globalSettingsPathOverride ?? join(homedir(), ".pi", SETTINGS_FILENAME);
+      const globalPath = getGlobalSettingsPath();
       cachedGlobalMtime = existsSync(globalPath) ? statSync(globalPath).mtimeMs : 0;
     } catch { cachedGlobalMtime = 0; }
     lastMtimeCheck = now;
@@ -267,7 +433,7 @@ function getSettings(cwd: string): ProjectSettings {
   if (now - lastMtimeCheck < MTIME_CHECK_INTERVAL_MS) return cachedSettings;
   lastMtimeCheck = now;
   const settingsPath = getSettingsPath(cwd);
-  const globalPath = globalSettingsPathOverride ?? join(homedir(), ".pi", SETTINGS_FILENAME);
+  const globalPath = getGlobalSettingsPath();
   let mtime = 0;
   let globalMtime = 0;
   try { if (existsSync(settingsPath)) mtime = statSync(settingsPath).mtimeMs; } catch {}
@@ -301,68 +467,57 @@ export function getSetting(cwd: string, key: "cli_agents"): string[];
 export function getSetting(cwd: string, key: "pidash_enable"): boolean;
 export function getSetting(cwd: string, key: "pidiff_enable"): boolean;
 export function getSetting(cwd: string, key: "pidash_port"): number;
+export function getSetting(cwd: string, key: "task_auto_clear_enabled"): boolean;
+export function getSetting(cwd: string, key: "task_auto_clear_minutes"): number;
+export function getSetting(cwd: string, key: "task_reminder_enabled"): boolean;
+export function getSetting(cwd: string, key: "task_reminder_interval_minutes"): number;
+export function getSetting(cwd: string, key: "task_stale_in_progress_enabled"): boolean;
+export function getSetting(cwd: string, key: "task_stale_in_progress_minutes"): number;
 export function getSetting(cwd: string, key: "image_model"): string;
-export function getSetting(cwd: string, key: "async_llm_provider"): string;
-export function getSetting(cwd: string, key: "async_llm_model"): string;
+export function getSetting(cwd: string, key: "internal_operations_provider"): string;
+export function getSetting(cwd: string, key: "internal_operations_model"): string;
 export function getSetting(cwd: string, key: "review_loop_max_cycles"): number;
 export function getSetting(cwd: string, key: "agent_provider"): string;
 export function getSetting(cwd: string, key: "agent_model"): string;
 export function getSetting(cwd: string, key: "agent_overrides"): Record<string, { provider?: string | null; model?: string | null }>;
+export function getSetting(cwd: string, key: "vertex_claude_1m"): boolean;
+export function getSetting(cwd: string, key: "sidecar_log_level"): string;
+export function getSetting(cwd: string, key: "enforcement_allowed_commands"): string;
+export function getSetting(cwd: string, key: "enforcement_loop_sleep_threshold_s"): number;
+export function getSetting(cwd: string, key: "enforcement_sleep_threshold_s"): number;
+export function getSetting(cwd: string, key: "sync_agent_max_seconds"): number;
+export function getSetting(cwd: string, key: "async_poll_interval_ms"): number;
+export function getSetting(cwd: string, key: "async_phantom_timeout_ms"): number;
+export function getSetting(cwd: string, key: "coms_max_hops"): number;
+export function getSetting(cwd: string, key: "coms_timeout_ms"): number;
+export function getSetting(cwd: string, key: "coms_dir"): string;
+export function getSetting(cwd: string, key: "coms_task_heartbeat_ms"): number;
+export function getSetting(cwd: string, key: "coms_entry_grace_period_ms"): number;
+export function getSetting(cwd: string, key: "coms_probe_timeout_ms"): number;
+export function getSetting(cwd: string, key: "pidiff_stale_lock_timeout_ms"): number;
+export function getSetting(cwd: string, key: "pidiff_daemon_startup_timeout_s"): number;
 export function getSetting(cwd: string, key: string): boolean | string | number | string[] | Record<string, { provider?: string | null; model?: string | null }> {
   const settings = getSettings(cwd);
+  const def = SETTINGS_KEYS[key];
+  if (!def) return false;
 
+  // Special cases — unique parsing beyond simple settings → env → default
   switch (key) {
     case "commit_trailer": {
       if (settings.commit_trailer !== undefined) return settings.commit_trailer;
-      const envStr = process.env.PI_COMMIT_TRAILER;
+      const envStr = def.env ? process.env[def.env] : undefined;
       if (envStr !== undefined && envStr !== "") {
         if (["true", "1", "yes", "on"].includes(envStr.toLowerCase())) return true;
         if (["false", "0", "no", "off"].includes(envStr.toLowerCase())) return false;
         return envStr; // treat as custom trailer string
       }
-      return false; // default: disabled
-    }
-    case "allow_push_to_protected_branches": {
-      if (settings.allow_push_to_protected_branches !== undefined) return settings.allow_push_to_protected_branches;
-      const env = parseBoolEnv("PI_ALLOW_PUSH_TO_PROTECTED_BRANCHES");
-      if (env !== undefined) return env;
-      return false; // default: block pushes to protected branches
-    }
-    case "use_worktrees": {
-      if (settings.use_worktrees !== undefined) return settings.use_worktrees;
-      const env = parseBoolEnv("PI_USE_WORKTREES");
-      if (env !== undefined) return env;
-      return false; // default: disabled
-    }
-    case "dream_interval_hours": {
-      if (settings.dream_interval_hours !== undefined) return settings.dream_interval_hours;
-      const env = parseNumEnv("PI_DREAM_INTERVAL_HOURS");
-      if (env !== undefined) return env;
-      return 3; // default: 3 hours
-    }
-    case "dco": {
-      if (settings.dco !== undefined) return settings.dco;
-      const env = parseBoolEnv("PI_DCO");
-      if (env !== undefined) return env;
-      return false; // default: disabled
-    }
-    case "comment_signature": {
-      if (settings.comment_signature !== undefined) return settings.comment_signature;
-      return false; // default: disabled
-    }
-    case "review_loop_enforcement": {
-      if (settings.review_loop_enforcement !== undefined) return settings.review_loop_enforcement;
-      const env = parseBoolEnv("PI_REVIEW_LOOP_ENFORCEMENT");
-      if (env !== undefined) return env;
-      return false; // default: disabled (opt-in)
+      return def.default as boolean;
     }
-    case "orchestrator_edit_write_block": {
-      if (settings.orchestrator_edit_write_block !== undefined) return settings.orchestrator_edit_write_block;
-      return false; // default: disabled
-    }
-    case "acpx_agents": {
-      if (projectSettingsFileHasKey(cwd, "acpx_agents")) {
-        const projectValue = loadProjectSettings(cwd).acpx_agents;
+    case "acpx_agents":
+    case "cli_agents": {
+      const agentKey = key as "acpx_agents" | "cli_agents";
+      if (projectSettingsFileHasKey(cwd, agentKey)) {
+        const projectValue = loadProjectSettings(cwd)[agentKey];
         // Only override when the raw value parsed as a valid type (string or array).
         // Invalid types (number, object, etc.) are skipped by parseSettingsFile,
         // leaving projectValue undefined — fall through to global/env.
@@ -370,44 +525,27 @@ export function getSetting(cwd: string, key: string): boolean | string | number
           return parseAgentNameList(projectValue);
         }
       }
-      const globalAgents = loadGlobalSettings().acpx_agents;
+      const globalAgents = loadGlobalSettings()[agentKey];
       if (globalAgents !== undefined) {
         return parseAgentNameList(globalAgents);
       }
-      const env = process.env.ACPX_AGENTS;
-      if (env !== undefined && env !== "") {
-        return parseAgentNameList(env);
-      }
-      return [];
-    }
-    case "cli_agents": {
-      if (projectSettingsFileHasKey(cwd, "cli_agents")) {
-        const projectValue = loadProjectSettings(cwd).cli_agents;
-        if (projectValue !== undefined) {
-          return parseAgentNameList(projectValue);
+      if (def.env) {
+        const env = process.env[def.env];
+        if (env !== undefined && env !== "") {
+          return parseAgentNameList(env);
         }
       }
-      const globalAgents = loadGlobalSettings().cli_agents;
-      if (globalAgents !== undefined) {
-        return parseAgentNameList(globalAgents);
-      }
-      const env = process.env.CLI_AGENTS;
-      if (env !== undefined && env !== "") {
-        return parseAgentNameList(env);
-      }
-      return [];
-    }
-    case "pidash_enable": {
-      if (settings.pidash_enable !== undefined) return settings.pidash_enable;
-      const disabled = parseDisabledEnv("PI_PIDASH_ENABLE");
-      if (disabled !== undefined) return !disabled;
-      return true;
+      return parseAgentNameList(def.default as string | string[] | undefined);
     }
+    case "pidash_enable":
     case "pidiff_enable": {
-      if (settings.pidiff_enable !== undefined) return settings.pidiff_enable;
-      const disabled = parseDisabledEnv("PI_PIDIFF_ENABLE");
-      if (disabled !== undefined) return !disabled;
-      return true;
+      const enableKey = key as "pidash_enable" | "pidiff_enable";
+      if (settings[enableKey] !== undefined) return settings[enableKey]!;
+      if (def.env) {
+        const disabled = parseDisabledEnv(def.env);
+        if (disabled !== undefined) return !disabled;
+      }
+      return def.default as boolean;
     }
     case "pidash_port": {
       if (settings.pidash_port !== undefined) {
@@ -417,39 +555,85 @@ export function getSetting(cwd: string, key: string): boolean | string | number
         }
         // Invalid value in merged settings — fall through to env/default
       }
-      const envPort = parsePortEnv("PI_PIDASH_PORT");
-      if (envPort !== undefined) return envPort;
-      return 19190;
+      if (def.env) {
+        const envPort = parsePortEnv(def.env);
+        if (envPort !== undefined) return envPort;
+      }
+      return def.default as number;
     }
-    case "image_model": {
-      if (settings.image_model !== undefined) return settings.image_model;
-      const env = process.env.PI_IMAGE_MODEL;
-      return env !== undefined && env !== "" ? env : "";
+    case "review_loop_max_cycles": {
+      if (settings.review_loop_max_cycles !== undefined) return settings.review_loop_max_cycles;
+      if (def.env) {
+        const env = parseReviewLoopMaxCyclesEnv(def.env);
+        if (env !== undefined) return env;
+      }
+      return def.default as number;
     }
-    case "async_llm_provider": {
-      if (settings.async_llm_provider !== undefined) return settings.async_llm_provider;
-      const env = process.env.PI_ASYNC_LLM_PROVIDER;
-      return env !== undefined && env !== "" ? env.trim() : "";
+    case "agent_overrides": {
+      return settings.agent_overrides || (def.default as Record<string, { provider?: string | null; model?: string | null }>);
     }
-    case "async_llm_model": {
-      if (settings.async_llm_model !== undefined) return settings.async_llm_model;
-      const env = process.env.PI_ASYNC_LLM_MODEL;
-      return env !== undefined && env !== "" ? env.trim() : "";
+  }
+
+  // Generic handler — simple bool / number / string keys driven by settings-keys.json
+  const merged = settings[key as keyof ProjectSettings];
+  switch (def.type) {
+    case "bool": {
+      if (merged !== undefined) return merged as boolean;
+      if (def.env) {
+        const env = parseBoolEnv(def.env);
+        if (env !== undefined) return env;
+      }
+      return def.default as boolean;
     }
-    case "review_loop_max_cycles": {
-      if (settings.review_loop_max_cycles !== undefined) return settings.review_loop_max_cycles;
-      const env = parseReviewLoopMaxCyclesEnv("PI_REVIEW_LOOP_MAX_CYCLES");
-      if (env !== undefined) return env;
-      return 3; // default: 3 cycles
+    case "int": {
+      if (merged !== undefined) return merged as number;
+      if (def.env) {
+        const val = process.env[def.env];
+        if (val !== undefined && val !== "") {
+          const trimmed = val.trim();
+          if (/^-?\d+$/.test(trimmed)) {
+            const n = Number(trimmed);
+            const min = def.min ?? 0;
+            const max = def.max ?? Number.MAX_SAFE_INTEGER;
+            if (n >= min && n <= max) return n;
+          }
+        }
+      }
+      return def.default as number;
     }
-    case "agent_provider": {
-      return settings.agent_provider || "";
+    case "port": {
+      if (merged !== undefined) {
+        const n = merged as number;
+        if (Number.isInteger(n) && n >= 0 && n <= 65535) return n;
+      }
+      if (def.env) {
+        const val = process.env[def.env];
+        if (val !== undefined && val !== "") {
+          const trimmed = val.trim();
+          if (/^\d+$/.test(trimmed)) {
+            const n = Number(trimmed);
+            if (n >= 0 && n <= 65535) return n;
+          }
+        }
+      }
+      return def.default as number;
     }
-    case "agent_model": {
-      return settings.agent_model || "";
+    case "number": {
+      if (merged !== undefined) return merged as number;
+      if (def.env) {
+        const env = parseNumEnv(def.env);
+        if (env !== undefined) return env;
+      }
+      return def.default as number;
     }
-    case "agent_overrides": {
-      return settings.agent_overrides || {};
+    case "string": {
+      // Preserve empty strings — some settings use empty as meaningful ("allow all", "use default dir")
+      if (merged !== undefined) return merged as string;
+      if (def.env) {
+        const env = process.env[def.env];
+        if (env !== undefined && env !== "") return env.trim();
+      }
+      return def.default as string;
     }
     default:
       return false;
@@ -464,5 +648,27 @@ export function registerProjectSettings(pi: ExtensionAPI): void {
 
   pi.on("session_start", (_event, ctx) => {
     clearSettingsCache();
+
+    // Inject settings into process.env for standalone packages that can't call getSetting
+    const cwd = ctx.cwd;
+    const vertexClaude1m = getSetting(cwd, "vertex_claude_1m");
+    if (vertexClaude1m) process.env.VERTEX_CLAUDE_1M = "true";
+    else delete process.env.VERTEX_CLAUDE_1M;
+
+    const sidecarLogLevel = getSetting(cwd, "sidecar_log_level");
+    if (sidecarLogLevel) process.env.PI_SIDECAR_LOG_LEVEL = sidecarLogLevel;
+    else delete process.env.PI_SIDECAR_LOG_LEVEL;
+
+    const acpxAgents = getSetting(cwd, "acpx_agents");
+    if (acpxAgents.length > 0) process.env.ACPX_AGENTS = acpxAgents.join(",");
+    else delete process.env.ACPX_AGENTS;
+
+    const cliAgents = getSetting(cwd, "cli_agents");
+    if (cliAgents.length > 0) process.env.CLI_AGENTS = cliAgents.join(",");
+    else delete process.env.CLI_AGENTS;
+
+    const imageModel = getSetting(cwd, "image_model");
+    if (imageModel) process.env.PI_IMAGE_MODEL = imageModel;
+    else delete process.env.PI_IMAGE_MODEL;
   });
 }

package/extensions/orchestrator/resolve-agent-model.ts

@@ -1,6 +1,7 @@
 /**
  * Resolve effective model/provider for an agent.
- * Priority: agent_overrides[name] > agent frontmatter > agent_provider/agent_model setting > parent
+ * Each field resolved independently through priority chain:
+ * explicit > agent_overrides[name] > agent frontmatter > agent_provider/agent_model setting > parent
  * null in overrides = skip settings, use parent directly.
  */
 
@@ -11,22 +12,32 @@ export function resolveAgentModelProvider(
   agent: { model?: string; provider?: string },
   parentModelId: string | undefined,
   parentProvider: string | undefined,
-  cwd: string
+  cwd: string,
+  explicit?: { model?: string; provider?: string },
 ): { model: string | undefined; provider: string | undefined } {
   const overrides = getSetting(cwd, "agent_overrides");
   const override = overrides[agentName];
 
-  if (override) {
-    // null = explicitly use parent (skip agent frontmatter AND global settings)
-    // Model and provider resolve independently on purpose: a partial override
-    // (e.g. only model) still lets provider fall through frontmatter → settings → parent.
-    const model = override.model === null ? parentModelId : (override.model || agent.model || getSetting(cwd, "agent_model") || parentModelId);
-    const provider = override.provider === null ? parentProvider : (override.provider || agent.provider || getSetting(cwd, "agent_provider") || parentProvider);
-    return { model: model || undefined, provider: provider || undefined };
+  // Resolve each field independently through the priority chain:
+  // explicit > agent_overrides[name] > agent frontmatter > agent_provider/agent_model setting > parent
+  // null in overrides = skip settings, use parent directly.
+  function resolveModel(): string | undefined {
+    if (explicit?.model) return explicit.model;
+    if (override) {
+      if (override.model === null) return parentModelId;
+      if (override.model) return override.model;
+    }
+    return agent.model || getSetting(cwd, "agent_model") || parentModelId || undefined;
   }
 
-  // No override: agent frontmatter > global setting > parent
-  const model = agent.model || getSetting(cwd, "agent_model") || parentModelId;
-  const provider = agent.provider || getSetting(cwd, "agent_provider") || parentProvider;
-  return { model: model || undefined, provider: provider || undefined };
+  function resolveProvider(): string | undefined {
+    if (explicit?.provider) return explicit.provider;
+    if (override) {
+      if (override.provider === null) return parentProvider;
+      if (override.provider) return override.provider;
+    }
+    return agent.provider || getSetting(cwd, "agent_provider") || parentProvider || undefined;
+  }
+
+  return { model: resolveModel(), provider: resolveProvider() };
 }