pi-advisor-flow 0.5.0 → 0.5.2

package/src/config/args.ts

@@ -0,0 +1,37 @@
+import {
+  advisorRef,
+  contextMaxCharsRef,
+  executorRef,
+  setAdvisorRef,
+  setContextMaxCharsRef,
+  setExecutorRef,
+} from "./state.js";
+import { MAX_CONTEXT_MAX_CHARS } from "./types.js";
+import { isValidContextMaxChars } from "./validation.js";
+
+const ARGUMENT_WHITESPACE = /\s+/;
+
+export const parseArgs = (args: string): string | undefined => {
+  let nextExecutor = executorRef;
+  let nextAdvisor = advisorRef;
+  let nextContextMaxChars = contextMaxCharsRef;
+  for (const token of args.trim().split(ARGUMENT_WHITESPACE).filter(Boolean)) {
+    const [key, value] = token.split("=");
+    if (key === "executor" && value) {
+      nextExecutor = value;
+    }
+    if (key === "advisor" && value) {
+      nextAdvisor = value;
+    }
+    if (key === "contextMaxChars") {
+      const parsed = Number(value);
+      if (!isValidContextMaxChars(parsed)) {
+        return `contextMaxChars must be a non-negative integer no greater than ${MAX_CONTEXT_MAX_CHARS}.`;
+      }
+      nextContextMaxChars = parsed;
+    }
+  }
+  setExecutorRef(nextExecutor);
+  setAdvisorRef(nextAdvisor);
+  setContextMaxCharsRef(nextContextMaxChars);
+};

package/src/config/defaults.ts

@@ -0,0 +1,190 @@
+import {
+  setAdvisorAutoLoopGateRef,
+  setAdvisorBlockOnBlockedRef,
+  setAdvisorCollapseResponsesRef,
+  setAdvisorCompletionGateRef,
+  setAdvisorCustomInvocationRef,
+  setAdvisorEffortRef,
+  setAdvisorFailureGateRef,
+  setAdvisorFailureModeRef,
+  setAdvisorGitContextMaxCharsRef,
+  setAdvisorGitContextRef,
+  setAdvisorHerdrIntegrationRef,
+  setAdvisorLoopThresholdRef,
+  setAdvisorMaxCallsPerSessionRef,
+  setAdvisorOutcomeLoggingRef,
+  setAdvisorPlanGateRef,
+  setAdvisorRedactSecretsRef,
+  setAdvisorRef,
+  setAdvisorScoutEnabledRef,
+  setAdvisorSessionSummaryRef,
+  setAdvisorToolPoliciesRef,
+  setAdvisorToolResultMaxBytesRef,
+  setAdvisorToolResultMaxLinesRef,
+  setAdvisorTrackedFileContentRef,
+  setAdvisorUntrackedContentRef,
+  setAlwaysOnRef,
+  setContextMaxCharsRef,
+  setExecutorEffortRef,
+  setExecutorRef,
+  setPersistedModelRefs,
+  setShowUsageDetailsRef,
+  setShowUsageFooterRef,
+  setSimpleModeRef,
+} from "./state.js";
+import type { AdvisorConfig } from "./types.js";
+import {
+  DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
+  DEFAULT_CONTEXT_MAX_CHARS,
+} from "./types.js";
+
+export const resetDefaults = () => {
+  setExecutorRef("");
+  setAdvisorRef("");
+  setPersistedModelRefs(undefined, undefined);
+  setExecutorEffortRef(undefined);
+  setAdvisorEffortRef(undefined);
+  setContextMaxCharsRef(DEFAULT_CONTEXT_MAX_CHARS);
+  setAdvisorPlanGateRef(true);
+  setAdvisorFailureGateRef(true);
+  setAdvisorCompletionGateRef(true);
+  setAdvisorCustomInvocationRef(undefined);
+  setAdvisorCollapseResponsesRef(false);
+  setAdvisorBlockOnBlockedRef(true);
+  setAdvisorAutoLoopGateRef(true);
+  setAdvisorLoopThresholdRef(3);
+  setAdvisorMaxCallsPerSessionRef(undefined);
+  setAdvisorSessionSummaryRef(false);
+  setSimpleModeRef(false);
+  setAlwaysOnRef(false);
+  setAdvisorFailureModeRef("block-session");
+  setAdvisorHerdrIntegrationRef(true);
+  setAdvisorToolResultMaxLinesRef(DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES);
+  setAdvisorToolResultMaxBytesRef(DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES);
+  setAdvisorRedactSecretsRef(false);
+  setAdvisorGitContextRef("summary");
+  setAdvisorGitContextMaxCharsRef(DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS);
+  setAdvisorToolPoliciesRef({});
+  setAdvisorOutcomeLoggingRef(false);
+  setAdvisorUntrackedContentRef(false);
+  setAdvisorTrackedFileContentRef(false);
+  setAdvisorScoutEnabledRef(false);
+  setShowUsageDetailsRef(true);
+  setShowUsageFooterRef(false);
+};
+
+const applyOptionalConfig = <Key extends keyof AdvisorConfig>(
+  config: AdvisorConfig,
+  key: Key,
+  apply: (value: NonNullable<AdvisorConfig[Key]>) => void
+) => {
+  const value = config[key];
+  if (value !== undefined) {
+    apply(value as NonNullable<AdvisorConfig[Key]>);
+  }
+};
+
+const applyNonEmptyStringConfig = (
+  value: string | undefined,
+  apply: (value: string) => void
+) => {
+  if (value) {
+    apply(value);
+  }
+};
+
+export const applyConfig = (config: AdvisorConfig) => {
+  applyNonEmptyStringConfig(config.executor, setExecutorRef);
+  applyNonEmptyStringConfig(config.advisor, setAdvisorRef);
+  applyNonEmptyStringConfig(config.executorEffort, setExecutorEffortRef);
+  applyNonEmptyStringConfig(config.advisorEffort, setAdvisorEffortRef);
+  applyOptionalConfig(config, "contextMaxChars", setContextMaxCharsRef);
+  applyOptionalConfig(config, "advisorPlanGate", setAdvisorPlanGateRef);
+  applyOptionalConfig(config, "advisorFailureGate", setAdvisorFailureGateRef);
+  applyOptionalConfig(
+    config,
+    "advisorCompletionGate",
+    setAdvisorCompletionGateRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorCustomInvocation",
+    setAdvisorCustomInvocationRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorCollapseResponses",
+    setAdvisorCollapseResponsesRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorBlockOnBlocked",
+    setAdvisorBlockOnBlockedRef
+  );
+  applyOptionalConfig(config, "advisorAutoLoopGate", setAdvisorAutoLoopGateRef);
+  applyOptionalConfig(
+    config,
+    "advisorLoopThreshold",
+    setAdvisorLoopThresholdRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorMaxCallsPerSession",
+    setAdvisorMaxCallsPerSessionRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorSessionSummary",
+    setAdvisorSessionSummaryRef
+  );
+  applyOptionalConfig(config, "advisorScoutEnabled", setAdvisorScoutEnabledRef);
+  applyOptionalConfig(config, "showUsageDetails", setShowUsageDetailsRef);
+  applyOptionalConfig(config, "showUsageFooter", setShowUsageFooterRef);
+  applyOptionalConfig(config, "simpleMode", setSimpleModeRef);
+  applyOptionalConfig(config, "alwaysOn", setAlwaysOnRef);
+  applyOptionalConfig(config, "gateFailureMode", setAdvisorFailureModeRef);
+  applyOptionalConfig(
+    config,
+    "advisorHerdrIntegration",
+    setAdvisorHerdrIntegrationRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorToolResultMaxLines",
+    setAdvisorToolResultMaxLinesRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorToolResultMaxBytes",
+    setAdvisorToolResultMaxBytesRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorRedactSecrets",
+    setAdvisorRedactSecretsRef
+  );
+  applyOptionalConfig(config, "advisorGitContext", setAdvisorGitContextRef);
+  applyOptionalConfig(
+    config,
+    "advisorGitContextMaxChars",
+    setAdvisorGitContextMaxCharsRef
+  );
+  applyOptionalConfig(config, "advisorToolPolicies", setAdvisorToolPoliciesRef);
+  applyOptionalConfig(
+    config,
+    "advisorUntrackedContent",
+    setAdvisorUntrackedContentRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorTrackedFileContent",
+    setAdvisorTrackedFileContentRef
+  );
+  applyOptionalConfig(
+    config,
+    "advisorOutcomeLogging",
+    setAdvisorOutcomeLoggingRef
+  );
+};

package/src/config/state.ts

@@ -0,0 +1,199 @@
+import type { GitContextLevel } from "../git.js";
+import {
+  type AdvisorToolPolicies,
+  DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
+  DEFAULT_CONTEXT_MAX_CHARS,
+  type GateFailureMode,
+} from "./types.js";
+
+// An empty ref means no model has been selected yet.
+export let executorRef = "";
+export let advisorRef = "";
+let persistedExecutorRef: string | undefined;
+let persistedAdvisorRef: string | undefined;
+export let executorEffortRef: string | undefined;
+export let advisorEffortRef: string | undefined;
+export let contextMaxCharsRef = DEFAULT_CONTEXT_MAX_CHARS;
+export let advisorPlanGateRef = true;
+export let advisorFailureGateRef = true;
+export let advisorCompletionGateRef = true;
+export let advisorCustomInvocationRef: string | undefined;
+export let advisorCollapseResponsesRef = false;
+export let advisorBlockOnBlockedRef = true;
+export let advisorAutoLoopGateRef = true;
+export let advisorLoopThresholdRef = 3;
+export let advisorMaxCallsPerSessionRef: number | undefined;
+export let advisorSessionSummaryRef = false;
+export let simpleModeRef = false;
+export let alwaysOnRef = false;
+export let advisorFailureModeRef: GateFailureMode = "block-session";
+export let advisorHerdrIntegrationRef = true;
+export let advisorToolResultMaxLinesRef = DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES;
+export let advisorToolResultMaxBytesRef = DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES;
+export let advisorRedactSecretsRef = false;
+export let advisorGitContextRef: GitContextLevel = "summary";
+export let advisorGitContextMaxCharsRef = DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS;
+export let advisorToolPoliciesRef: AdvisorToolPolicies = {};
+export let advisorOutcomeLoggingRef = false;
+export let advisorUntrackedContentRef = false;
+export let advisorTrackedFileContentRef = false;
+export let advisorScoutEnabledRef = false;
+export let showUsageDetailsRef = true;
+export let showUsageFooterRef = false;
+
+export const setExecutorRef = (ref: string) => {
+  executorRef = ref;
+};
+export const setAdvisorRef = (ref: string) => {
+  advisorRef = ref;
+};
+/** Returns model refs explicitly persisted in the global Advisor config. */
+export const getPersistedModelRefs = () => ({
+  advisor: persistedAdvisorRef,
+  executor: persistedExecutorRef,
+});
+
+/** Updates persisted model refs without exposing the mutation in the facade. */
+export const setPersistedModelRefs = (
+  advisor: string | undefined,
+  executor: string | undefined
+) => {
+  persistedAdvisorRef = advisor;
+  persistedExecutorRef = executor;
+};
+
+export const setExecutorEffortRef = (effort: string | undefined) => {
+  executorEffortRef = effort;
+};
+export const setAdvisorEffortRef = (effort: string | undefined) => {
+  advisorEffortRef = effort;
+};
+export const setContextMaxCharsRef = (value: number) => {
+  contextMaxCharsRef = value;
+};
+export const setAdvisorPlanGateRef = (enabled: boolean) => {
+  advisorPlanGateRef = enabled;
+};
+export const setAdvisorFailureGateRef = (enabled: boolean) => {
+  advisorFailureGateRef = enabled;
+};
+export const setAdvisorCompletionGateRef = (enabled: boolean) => {
+  advisorCompletionGateRef = enabled;
+};
+export const setAdvisorCustomInvocationRef = (rule: string | undefined) => {
+  advisorCustomInvocationRef = rule?.trim() || undefined;
+};
+export const setAdvisorCollapseResponsesRef = (enabled: boolean) => {
+  advisorCollapseResponsesRef = enabled;
+};
+export const setAdvisorBlockOnBlockedRef = (enabled: boolean) => {
+  advisorBlockOnBlockedRef = enabled;
+};
+export const setAdvisorAutoLoopGateRef = (enabled: boolean) => {
+  advisorAutoLoopGateRef = enabled;
+};
+export const setAdvisorLoopThresholdRef = (value: number) => {
+  advisorLoopThresholdRef = value;
+};
+export const setAdvisorMaxCallsPerSessionRef = (value: number | undefined) => {
+  advisorMaxCallsPerSessionRef = value;
+};
+export const setAdvisorSessionSummaryRef = (enabled: boolean) => {
+  advisorSessionSummaryRef = enabled;
+};
+export const setSimpleModeRef = (enabled: boolean) => {
+  simpleModeRef = enabled;
+};
+export const setAlwaysOnRef = (enabled: boolean) => {
+  alwaysOnRef = enabled;
+};
+/** Whether advanced Advisor automation is suppressed for this session. */
+export const isSimpleMode = () => simpleModeRef;
+export const setAdvisorFailureModeRef = (value: GateFailureMode) => {
+  advisorFailureModeRef = value;
+};
+export const setAdvisorHerdrIntegrationRef = (enabled: boolean) => {
+  advisorHerdrIntegrationRef = enabled;
+};
+export const setAdvisorToolResultMaxLinesRef = (value: number) => {
+  advisorToolResultMaxLinesRef = value;
+};
+export const setAdvisorToolResultMaxBytesRef = (value: number) => {
+  advisorToolResultMaxBytesRef = value;
+};
+export const setAdvisorRedactSecretsRef = (enabled: boolean) => {
+  advisorRedactSecretsRef = enabled;
+};
+export const setAdvisorGitContextRef = (level: GitContextLevel) => {
+  advisorGitContextRef = level;
+};
+export const setAdvisorGitContextMaxCharsRef = (value: number) => {
+  advisorGitContextMaxCharsRef = value;
+};
+export const setAdvisorToolPoliciesRef = (policies: AdvisorToolPolicies) => {
+  advisorToolPoliciesRef = { ...policies };
+};
+export const setAdvisorOutcomeLoggingRef = (enabled: boolean) => {
+  advisorOutcomeLoggingRef = enabled;
+};
+export const setAdvisorUntrackedContentRef = (enabled: boolean) => {
+  advisorUntrackedContentRef = enabled;
+};
+export const setAdvisorTrackedFileContentRef = (enabled: boolean) => {
+  advisorTrackedFileContentRef = enabled;
+};
+export const setAdvisorScoutEnabledRef = (enabled: boolean) => {
+  advisorScoutEnabledRef = enabled;
+};
+export const setShowUsageDetailsRef = (enabled: boolean) => {
+  showUsageDetailsRef = enabled;
+};
+export const setShowUsageFooterRef = (enabled: boolean) => {
+  showUsageFooterRef = enabled;
+};
+
+/**
+ * Returns the current live settings state. Use this at UI boundaries instead of
+ * imported mutable bindings, which can be snapshotted by extension loaders.
+ */
+export const getAdvisorSettings = () => ({
+  alwaysOn: alwaysOnRef,
+  autoLoopGate: advisorAutoLoopGateRef,
+  blockOnBlocked: advisorBlockOnBlockedRef,
+  collapseResponses: advisorCollapseResponsesRef,
+  completionGate: advisorCompletionGateRef,
+  contextMaxChars: contextMaxCharsRef,
+  customRule: advisorCustomInvocationRef,
+  effort: advisorEffortRef,
+  failureGate: advisorFailureGateRef,
+  failureMode: advisorFailureModeRef,
+  gitContext: advisorGitContextRef,
+  gitContextMaxChars: advisorGitContextMaxCharsRef,
+  herdrIntegration: advisorHerdrIntegrationRef,
+  loopThreshold: advisorLoopThresholdRef,
+  maxCallsPerSession: advisorMaxCallsPerSessionRef,
+  outcomeLogging: advisorOutcomeLoggingRef,
+  planGate: advisorPlanGateRef,
+  redactSecrets: advisorRedactSecretsRef,
+  scoutEnabled: advisorScoutEnabledRef,
+  sessionSummary: advisorSessionSummaryRef,
+  showUsageDetails: showUsageDetailsRef,
+  showUsageFooter: showUsageFooterRef,
+  simpleMode: simpleModeRef,
+  toolPolicies: { ...advisorToolPoliciesRef },
+  toolResultMaxBytes: advisorToolResultMaxBytesRef,
+  toolResultMaxLines: advisorToolResultMaxLinesRef,
+  trackedFileContent: advisorTrackedFileContentRef,
+  untrackedContent: advisorUntrackedContentRef,
+});
+
+/** Reads the live session budget at each enforcement boundary. */
+export const getAdvisorMaxCallsPerSession = () =>
+  getAdvisorSettings().maxCallsPerSession;
+
+export const splitRef = (ref: string): [string, string] => {
+  const i = ref.indexOf("/");
+  return i === -1 ? ["openai-codex", ref] : [ref.slice(0, i), ref.slice(i + 1)];
+};

package/src/config/storage.ts

@@ -0,0 +1,224 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  CONFIG_DIR_NAME,
+  type ExtensionContext,
+  getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import { applyConfig, resetDefaults } from "./defaults.js";
+import {
+  advisorAutoLoopGateRef,
+  advisorBlockOnBlockedRef,
+  advisorCollapseResponsesRef,
+  advisorCompletionGateRef,
+  advisorCustomInvocationRef,
+  advisorEffortRef,
+  advisorFailureGateRef,
+  advisorFailureModeRef,
+  advisorGitContextMaxCharsRef,
+  advisorGitContextRef,
+  advisorHerdrIntegrationRef,
+  advisorLoopThresholdRef,
+  advisorMaxCallsPerSessionRef,
+  advisorPlanGateRef,
+  advisorRedactSecretsRef,
+  advisorRef,
+  advisorScoutEnabledRef,
+  advisorSessionSummaryRef,
+  advisorToolPoliciesRef,
+  advisorToolResultMaxBytesRef,
+  advisorToolResultMaxLinesRef,
+  advisorTrackedFileContentRef,
+  advisorUntrackedContentRef,
+  alwaysOnRef,
+  contextMaxCharsRef,
+  executorEffortRef,
+  executorRef,
+  setAdvisorOutcomeLoggingRef,
+  setPersistedModelRefs,
+  showUsageDetailsRef,
+  showUsageFooterRef,
+  simpleModeRef,
+} from "./state.js";
+import type { AdvisorConfig } from "./types.js";
+import { unknownConfigKeys, validateConfig } from "./validation.js";
+
+export const configPaths = (ctx: ExtensionContext) => [
+  ctx.isProjectTrusted()
+    ? join(ctx.cwd, CONFIG_DIR_NAME, "advisor.json")
+    : null,
+  join(getAgentDir(), "advisor.json"),
+];
+
+const configuredModelRef = (value: string | undefined): string | undefined =>
+  value?.trim() || undefined;
+
+const readConfig = (path: string): AdvisorConfig => {
+  try {
+    const config = JSON.parse(readFileSync(path, "utf8"));
+    validateConfig(config, path);
+    return config;
+  } catch (error) {
+    throw error instanceof Error ? error : new Error(String(error));
+  }
+};
+
+// loadConfig runs on every tool call and every consultation. Caching the parsed
+// file by path and stat identity removes that read and parse from the hot path
+// while still applying the full reset-then-apply sequence on each call.
+const configCache = new Map<
+  string,
+  { config: AdvisorConfig; identity: string }
+>();
+const warnedUnknownConfigIdentities = new Set<string>();
+
+/** Drops the parsed-configuration cache; the next load re-reads from disk. */
+export const resetConfigCache = () => {
+  configCache.clear();
+  warnedUnknownConfigIdentities.clear();
+};
+
+/**
+ * Nanosecond timestamps plus size and inode so a same-millisecond or
+ * same-size external rewrite cannot be served from the cache. An unstattable
+ * path yields a unique value, which always forces a re-read.
+ */
+const configIdentity = (path: string): string => {
+  try {
+    const stats = statSync(path, { bigint: true });
+    return `${stats.mtimeNs}:${stats.ctimeNs}:${stats.size}:${stats.ino}:${stats.dev}`;
+  } catch {
+    return `unstattable:${process.hrtime.bigint()}`;
+  }
+};
+
+const readConfigCached = (path: string): AdvisorConfig => {
+  const identity = configIdentity(path);
+  const cached = configCache.get(path);
+  if (cached?.identity === identity) {
+    return cached.config;
+  }
+  const config = readConfig(path);
+  configCache.set(path, { config, identity });
+  return config;
+};
+
+export const loadConfig = (_ctx: ExtensionContext) => {
+  resetDefaults();
+  const global = join(getAgentDir(), "advisor.json");
+  const globalConfig = existsSync(global)
+    ? readConfigCached(global)
+    : undefined;
+  setPersistedModelRefs(
+    configuredModelRef(globalConfig?.advisor),
+    configuredModelRef(globalConfig?.executor)
+  );
+  if (globalConfig) {
+    applyConfig(globalConfig);
+    const unknownKeys = unknownConfigKeys(
+      globalConfig as Record<string, unknown>
+    );
+    const warningIdentity = `${global}:${configIdentity(global)}`;
+    if (
+      unknownKeys.length > 0 &&
+      _ctx.hasUI &&
+      !warnedUnknownConfigIdentities.has(warningIdentity)
+    ) {
+      _ctx.ui.notify(
+        `Advisor configuration at ${global} contains unrecognized key(s) ${unknownKeys.map((key) => JSON.stringify(key)).join(", ")}. They were preserved but ignored; check for typos or upgrade pi-advisor.`,
+        "warning"
+      );
+      warnedUnknownConfigIdentities.add(warningIdentity);
+    }
+  }
+  // Repository-controlled project configuration is never applied. Models,
+  // prompts, gates, budgets, disclosure, redaction, integrations, and consent
+  // remain under the user's global Pi configuration.
+  setAdvisorOutcomeLoggingRef(globalConfig?.advisorOutcomeLogging === true);
+  return existsSync(global) ? global : null;
+};
+
+/** Saves user-controlled configuration globally without outcome consent. */
+export interface SaveConfigOptions {
+  persistAdvisor?: boolean;
+  persistExecutor?: boolean;
+}
+
+export const saveConfig = (
+  _ctx: ExtensionContext,
+  options: SaveConfigOptions = {}
+) => {
+  const path = join(getAgentDir(), "advisor.json");
+  const persistAdvisor = options.persistAdvisor ?? true;
+  const persistExecutor = options.persistExecutor ?? true;
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      existing = parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* replace a missing or malformed file */
+  }
+  if (advisorMaxCallsPerSessionRef === undefined) {
+    existing.advisorMaxCallsPerSession = undefined;
+  }
+  const data = {
+    ...existing,
+    ...(persistAdvisor && advisorRef ? { advisor: advisorRef } : {}),
+    advisorAutoLoopGate: advisorAutoLoopGateRef,
+    advisorBlockOnBlocked: advisorBlockOnBlockedRef,
+    advisorCollapseResponses: advisorCollapseResponsesRef,
+    advisorCompletionGate: advisorCompletionGateRef,
+    advisorCustomInvocation: advisorCustomInvocationRef,
+    advisorEffort: advisorEffortRef,
+    advisorFailureGate: advisorFailureGateRef,
+    advisorLoopThreshold: advisorLoopThresholdRef,
+    advisorPlanGate: advisorPlanGateRef,
+    contextMaxChars: contextMaxCharsRef,
+    ...(persistExecutor && executorRef ? { executor: executorRef } : {}),
+    executorEffort: executorEffortRef,
+    ...(advisorMaxCallsPerSessionRef === undefined
+      ? {}
+      : { advisorMaxCallsPerSession: advisorMaxCallsPerSessionRef }),
+    advisorGitContext: advisorGitContextRef,
+    advisorGitContextMaxChars: advisorGitContextMaxCharsRef,
+    advisorHerdrIntegration: advisorHerdrIntegrationRef,
+    advisorRedactSecrets: advisorRedactSecretsRef,
+    advisorScoutEnabled: advisorScoutEnabledRef,
+    advisorSessionSummary: advisorSessionSummaryRef,
+    advisorToolPolicies: advisorToolPoliciesRef,
+    advisorToolResultMaxBytes: advisorToolResultMaxBytesRef,
+    advisorToolResultMaxLines: advisorToolResultMaxLinesRef,
+    advisorTrackedFileContent: advisorTrackedFileContentRef,
+    advisorUntrackedContent: advisorUntrackedContentRef,
+    alwaysOn: alwaysOnRef,
+    gateFailureMode: advisorFailureModeRef,
+    showUsageDetails: showUsageDetailsRef,
+    showUsageFooter: showUsageFooterRef,
+    simpleMode: simpleModeRef,
+  };
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
+  resetConfigCache();
+  return path;
+};
+
+/** Outcome logging is deliberately written only to the global Pi configuration. */
+export const saveGlobalOutcomeLogging = (enabled: boolean) => {
+  const path = join(getAgentDir(), "advisor.json");
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      existing = parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* create it */
+  }
+  writeFileSync(
+    path,
+    `${JSON.stringify({ ...existing, advisorOutcomeLogging: enabled }, null, 2)}\n`
+  );
+  resetConfigCache();
+  return path;
+};