pi-advisor-flow 0.2.3 → 0.2.6

package/src/config.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   CONFIG_DIR_NAME,
@@ -7,6 +7,11 @@ import {
   type ExtensionContext,
   getAgentDir,
 } from "@earendil-works/pi-coding-agent";
+import {
+  GIT_CONTEXT_LEVELS,
+  type GitContextLevel,
+  isValidGitContextLevel,
+} from "./git.js";
 
 export const FALLBACK_EXECUTOR = "aikeys/claude-sonnet-5";
 export const FALLBACK_ADVISOR = "aikeys/claude-fable-5";
@@ -14,6 +19,7 @@ export const DEFAULT_CONTEXT_MAX_CHARS = 15_000;
 export const MAX_CONTEXT_MAX_CHARS = Number.MAX_SAFE_INTEGER;
 export const DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES = DEFAULT_MAX_LINES;
 export const DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES;
+export const DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS = 20_000;
 export type AdvisorToolPolicy = "full" | "summary" | "exclude";
 export type AdvisorToolPolicies = Record<string, AdvisorToolPolicy>;
 export const ADVISOR_TOOL_POLICIES: AdvisorToolPolicy[] = [
@@ -45,13 +51,19 @@ export let advisorBlockOnBlockedRef = true;
 export let advisorAutoLoopGateRef = true;
 export let advisorLoopThresholdRef = 3;
 export let advisorMaxCallsPerSessionRef: number | undefined;
-export let advisorSessionSummaryRef = true;
+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 const setExecutorRef = (ref: string) => {
   executorRef = ref;
@@ -107,6 +119,14 @@ export const setAdvisorMaxCallsPerSessionRef = (value: number | undefined) => {
 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 isValidGateFailureMode = (
   value: unknown
 ): value is GateFailureMode =>
@@ -131,15 +151,28 @@ export const setAdvisorToolResultMaxBytesRef = (value: number) => {
 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;
+};
 
 /**
  * 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,
@@ -149,15 +182,20 @@ export const getAdvisorSettings = () => ({
   effort: advisorEffortRef,
   failureGate: advisorFailureGateRef,
   failureMode: advisorFailureModeRef,
+  gitContext: advisorGitContextRef,
+  gitContextMaxChars: advisorGitContextMaxCharsRef,
   herdrIntegration: advisorHerdrIntegrationRef,
   loopThreshold: advisorLoopThresholdRef,
   maxCallsPerSession: advisorMaxCallsPerSessionRef,
+  outcomeLogging: advisorOutcomeLoggingRef,
   planGate: advisorPlanGateRef,
   redactSecrets: advisorRedactSecretsRef,
   sessionSummary: advisorSessionSummaryRef,
+  simpleMode: simpleModeRef,
   toolPolicies: { ...advisorToolPoliciesRef },
   toolResultMaxBytes: advisorToolResultMaxBytesRef,
   toolResultMaxLines: advisorToolResultMaxLinesRef,
+  untrackedContent: advisorUntrackedContentRef,
 });
 
 export const splitRef = (ref: string): [string, string] => {
@@ -181,19 +219,25 @@ export interface AdvisorConfig {
   advisorCustomInvocation?: string;
   advisorEffort?: string;
   advisorFailureGate?: boolean;
+  advisorGitContext?: GitContextLevel;
+  advisorGitContextMaxChars?: number;
   advisorHerdrIntegration?: boolean;
   advisorLoopThreshold?: number;
   advisorMaxCallsPerSession?: number;
+  advisorOutcomeLogging?: boolean;
   advisorPlanGate?: boolean;
   advisorRedactSecrets?: boolean;
   advisorSessionSummary?: boolean;
   advisorToolPolicies?: AdvisorToolPolicies;
   advisorToolResultMaxBytes?: number;
   advisorToolResultMaxLines?: number;
+  advisorUntrackedContent?: boolean;
+  alwaysOn?: boolean;
   contextMaxChars?: number;
   executor?: string;
   executorEffort?: string;
   gateFailureMode?: GateFailureMode;
+  simpleMode?: boolean;
 }
 
 const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
@@ -205,14 +249,20 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "advisorCustomInvocation",
   "advisorEffort",
   "advisorFailureGate",
+  "advisorGitContext",
+  "advisorGitContextMaxChars",
   "advisorHerdrIntegration",
   "advisorLoopThreshold",
   "advisorMaxCallsPerSession",
   "advisorPlanGate",
   "advisorSessionSummary",
+  "simpleMode",
+  "alwaysOn",
   "advisorToolResultMaxBytes",
   "advisorToolResultMaxLines",
   "advisorRedactSecrets",
+  "advisorUntrackedContent",
+  "advisorOutcomeLogging",
   "advisorToolPolicies",
   "contextMaxChars",
   "executor",
@@ -227,8 +277,12 @@ const BOOLEAN_CONFIG_KEYS = [
   "advisorBlockOnBlocked",
   "advisorAutoLoopGate",
   "advisorSessionSummary",
+  "simpleMode",
+  "alwaysOn",
   "advisorHerdrIntegration",
   "advisorRedactSecrets",
+  "advisorUntrackedContent",
+  "advisorOutcomeLogging",
 ] as const;
 const STRING_CONFIG_KEYS = [
   "executor",
@@ -329,6 +383,11 @@ const validateNumericValues = (config: ConfigRecord, path: string) => {
       isValidToolResultMaxBytes,
       "a non-negative safe integer",
     ],
+    [
+      "advisorGitContextMaxChars",
+      isValidToolResultMaxBytes,
+      "a non-negative safe integer",
+    ],
   ];
   for (const [key, isValid, description] of numericRules) {
     if (config[key] !== undefined && !isValid(config[key])) {
@@ -367,6 +426,16 @@ export const validateConfig = (
   ) {
     invalidConfigValue(path, "gateFailureMode", GATE_FAILURE_MODES.join(", "));
   }
+  if (
+    config.advisorGitContext !== undefined &&
+    !isValidGitContextLevel(config.advisorGitContext)
+  ) {
+    invalidConfigValue(
+      path,
+      "advisorGitContext",
+      GIT_CONTEXT_LEVELS.join(", ")
+    );
+  }
   return true;
 };
 
@@ -385,13 +454,19 @@ const resetDefaults = () => {
   advisorAutoLoopGateRef = true;
   advisorLoopThresholdRef = 3;
   advisorMaxCallsPerSessionRef = undefined;
-  advisorSessionSummaryRef = true;
+  advisorSessionSummaryRef = false;
+  simpleModeRef = false;
+  alwaysOnRef = false;
   advisorFailureModeRef = "block-session";
   advisorHerdrIntegrationRef = true;
   advisorToolResultMaxLinesRef = DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES;
   advisorToolResultMaxBytesRef = DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES;
   advisorRedactSecretsRef = false;
+  advisorGitContextRef = "summary";
+  advisorGitContextMaxCharsRef = DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS;
   advisorToolPoliciesRef = {};
+  advisorOutcomeLoggingRef = false;
+  advisorUntrackedContentRef = false;
 };
 
 const applyOptionalConfig = <Key extends keyof AdvisorConfig>(
@@ -458,6 +533,8 @@ const applyConfig = (config: AdvisorConfig) => {
     "advisorSessionSummary",
     setAdvisorSessionSummaryRef
   );
+  applyOptionalConfig(config, "simpleMode", setSimpleModeRef);
+  applyOptionalConfig(config, "alwaysOn", setAlwaysOnRef);
   applyOptionalConfig(config, "gateFailureMode", setAdvisorFailureModeRef);
   applyOptionalConfig(
     config,
@@ -479,7 +556,18 @@ const applyConfig = (config: AdvisorConfig) => {
     "advisorRedactSecrets",
     setAdvisorRedactSecretsRef
   );
+  applyOptionalConfig(config, "advisorGitContext", setAdvisorGitContextRef);
+  applyOptionalConfig(
+    config,
+    "advisorGitContextMaxChars",
+    setAdvisorGitContextMaxCharsRef
+  );
   applyOptionalConfig(config, "advisorToolPolicies", setAdvisorToolPoliciesRef);
+  applyOptionalConfig(
+    config,
+    "advisorUntrackedContent",
+    setAdvisorUntrackedContentRef
+  );
 };
 
 const readConfig = (path: string): AdvisorConfig => {
@@ -492,19 +580,64 @@ const readConfig = (path: string): AdvisorConfig => {
   }
 };
 
+// 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.
+let configCache:
+  | { config: AdvisorConfig; identity: string; path: string }
+  | undefined;
+
+/** Drops the parsed-configuration cache; the next load re-reads from disk. */
+export const resetConfigCache = () => {
+  configCache = undefined;
+};
+
+/**
+ * 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;
+  if (cached && cached.path === path && cached.identity === identity) {
+    return cached.config;
+  }
+  const config = readConfig(path);
+  configCache = { config, identity, path };
+  return config;
+};
+
 export const loadConfig = (ctx: ExtensionContext) => {
   resetDefaults();
-  const path = configPaths(ctx).find(
+  const paths = configPaths(ctx);
+  const path = paths.find(
     (candidate): candidate is string =>
       candidate !== null && existsSync(candidate)
   );
-  if (!path) {
-    return null;
+  if (path) {
+    applyConfig(readConfigCached(path));
   }
-  applyConfig(readConfig(path));
-  return path;
+  // Persistent outcome consent is global-only: project configuration cannot enable it.
+  const global = join(getAgentDir(), "advisor.json");
+  const globalConfig = existsSync(global)
+    ? readConfigCached(global)
+    : undefined;
+  // Never apply this field through project-first configuration selection.
+  advisorOutcomeLoggingRef = globalConfig?.advisorOutcomeLogging === true;
+  return path ?? null;
 };
 
+/** Saves the ordinary project-preferred configuration without outcome consent. */
 export const saveConfig = (ctx: ExtensionContext) => {
   const project = join(ctx.cwd, CONFIG_DIR_NAME, "advisor.json");
   const path =
@@ -541,15 +674,41 @@ export const saveConfig = (ctx: ExtensionContext) => {
     ...(advisorMaxCallsPerSessionRef === undefined
       ? {}
       : { advisorMaxCallsPerSession: advisorMaxCallsPerSessionRef }),
+    advisorGitContext: advisorGitContextRef,
+    advisorGitContextMaxChars: advisorGitContextMaxCharsRef,
     advisorHerdrIntegration: advisorHerdrIntegrationRef,
     advisorRedactSecrets: advisorRedactSecretsRef,
     advisorSessionSummary: advisorSessionSummaryRef,
     advisorToolPolicies: advisorToolPoliciesRef,
     advisorToolResultMaxBytes: advisorToolResultMaxBytesRef,
     advisorToolResultMaxLines: advisorToolResultMaxLinesRef,
+    advisorUntrackedContent: advisorUntrackedContentRef,
+    alwaysOn: alwaysOnRef,
     gateFailureMode: advisorFailureModeRef,
+    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;
 };
 

package/src/conversation.ts

@@ -59,6 +59,23 @@ export const redactSecrets = (value: string): string => {
   return redacted;
 };
 
+/** Redacts before a byte-safe cap so no secret fragment survives truncation. */
+export const redactAndCapText = (
+  value: string,
+  maxBytes: number,
+  redact = true
+): string => {
+  const source = redact ? redactSecrets(value) : value;
+  let result = "";
+  for (const character of source) {
+    if (byteLength(result + character) > maxBytes) {
+      break;
+    }
+    result += character;
+  }
+  return result;
+};
+
 export interface ToolResultTruncation {
   content: string;
   omittedLines: number;
@@ -256,10 +273,18 @@ const selectRecentEntries = (entries: string[], maxChars: number): string => {
     return joined;
   }
   const selected: string[] = [];
+  // Track the joined length instead of re-joining the accumulator each step;
+  // long branches with a large maxChars are otherwise quadratic in bytes.
+  let selectedLength = 0;
   for (let index = entries.length - 1; index >= 0; index -= 1) {
-    const candidate = [entries[index], ...selected].join(separator);
-    if (candidate.length <= maxChars || selected.length === 0) {
-      selected.unshift(entries[index]);
+    const entry = entries[index];
+    const candidateLength =
+      selectedLength +
+      entry.length +
+      (selected.length === 0 ? 0 : separator.length);
+    if (candidateLength <= maxChars || selected.length === 0) {
+      selected.unshift(entry);
+      selectedLength = candidateLength;
     } else {
       break;
     }

package/src/git.ts

@@ -0,0 +1,190 @@
+import { execFileSync } from "node:child_process";
+
+/** How much repository change context may leave the machine. */
+export type GitContextLevel = "off" | "summary" | "full";
+
+export const GIT_CONTEXT_LEVELS: GitContextLevel[] = ["off", "summary", "full"];
+
+export const isValidGitContextLevel = (
+  value: unknown
+): value is GitContextLevel =>
+  GIT_CONTEXT_LEVELS.includes(value as GitContextLevel);
+
+const LEVEL_RANK: Record<GitContextLevel, number> = {
+  full: 2,
+  off: 0,
+  summary: 1,
+};
+
+/**
+ * The Executor may request no more repository context than the user configured.
+ * A model cannot widen its own disclosure allowance.
+ */
+export const clampGitContextLevel = (
+  requested: GitContextLevel,
+  allowed: GitContextLevel
+): GitContextLevel =>
+  LEVEL_RANK[requested] <= LEVEL_RANK[allowed] ? requested : allowed;
+
+export type GitContextStatus =
+  | "disabled"
+  | "no-changes"
+  | "collected"
+  | "not-a-repository"
+  | "failed";
+
+export interface GitContextResult {
+  /** Why collection produced nothing, for diagnostics. Never sent verbatim. */
+  detail?: string;
+  /** The level actually collected after clamping. */
+  level: GitContextLevel;
+  status: GitContextStatus;
+  /** Collected context, not yet escaped or capped. Empty when nothing is disclosed. */
+  text: string;
+}
+
+/**
+ * Repository text is attacker-influenced and is embedded in a tagged region.
+ * A path can reproduce a closing tag verbatim: a directory named `x<` holding a
+ * file named `repository_changes>` prints as `x</repository_changes>`, which
+ * would end the region early and promote the remainder to trusted instructions.
+ */
+export const escapeRepositoryText = (value: string) =>
+  value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const TRUNCATION_NOTICE =
+  "\n[Repository context truncated: it exceeded the configured limit.]";
+
+/** Caps the fully rendered region and states plainly that content was dropped. */
+export const capRepositoryContext = (value: string, maxChars: number) => {
+  if (value.length <= maxChars) {
+    return { text: value, truncated: false };
+  }
+  return {
+    text: `${value.slice(0, Math.max(0, maxChars - TRUNCATION_NOTICE.length))}${TRUNCATION_NOTICE}`,
+    truncated: true,
+  };
+};
+
+// git's own empty-tree object, used to diff a repository with no commits yet.
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const GIT_TOTAL_TIMEOUT_MS = 5000;
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+
+export type GitRunner = (args: string[], cwd: string) => string;
+
+/**
+ * Collection runs several git commands. A per-command timeout alone would let a
+ * pathological repository block for the sum of them, so the budget is shared:
+ * each command may use only the time remaining before the overall deadline.
+ */
+const deadlineRunner = (): GitRunner => {
+  const expiresAt = Date.now() + GIT_TOTAL_TIMEOUT_MS;
+  return (args, cwd) => {
+    const remaining = expiresAt - Date.now();
+    if (remaining <= 0) {
+      throw new Error("Git context collection exceeded its time budget.");
+    }
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: GIT_MAX_BUFFER,
+      // Never use a shell: arguments are fixed and must not be re-parsed.
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: remaining,
+      windowsHide: true,
+    });
+  };
+};
+
+/** Resolves the base revision, falling back to the empty tree before any commit. */
+const diffBase = (run: GitRunner, cwd: string): string => {
+  try {
+    run(["rev-parse", "--verify", "--quiet", "HEAD"], cwd);
+    return "HEAD";
+  } catch {
+    return EMPTY_TREE;
+  }
+};
+
+/**
+ * Collects working-tree changes relative to HEAD, covering staged and unstaged
+ * work. Untracked files are reported by name only and never by content.
+ *
+ * `summary` discloses file names, change status, and line counts. It must not
+ * include diff hunk headers: git derives those from surrounding file content,
+ * so they can reproduce a secret from a line the change never touched.
+ */
+export const collectGitContext = (
+  cwd: string,
+  level: GitContextLevel,
+  maxChars: number,
+  redact: (value: string) => string = (value) => value,
+  run: GitRunner = deadlineRunner()
+): GitContextResult => {
+  if (level === "off" || maxChars <= 0) {
+    return { level: "off", status: "disabled", text: "" };
+  }
+  try {
+    run(["rev-parse", "--is-inside-work-tree"], cwd);
+  } catch (error) {
+    return {
+      detail: error instanceof Error ? error.message : String(error),
+      level,
+      status: "not-a-repository",
+      text: "",
+    };
+  }
+
+  try {
+    const base = diffBase(run, cwd);
+    const nameStatus = run(["diff", "--name-status", base], cwd).trim();
+    const shortstat = run(["diff", "--shortstat", base], cwd).trim();
+    const untracked = run(
+      ["ls-files", "--others", "--exclude-standard"],
+      cwd
+    ).trim();
+
+    if (!(nameStatus || untracked)) {
+      return { level, status: "no-changes", text: "" };
+    }
+
+    const sections = [
+      "Working-tree changes against the last commit (staged and unstaged).",
+      nameStatus ? `Changed files:\n${nameStatus}` : "",
+      shortstat ? `Totals: ${shortstat}` : "",
+      untracked
+        ? `Untracked files (names only, contents withheld):\n${untracked}`
+        : "",
+    ];
+
+    if (level === "full") {
+      const patch = run(["diff", base], cwd);
+      sections.push(
+        patch.trim()
+          ? `Patch:\n${patch}`
+          : "Patch: (no tracked-file content changes)"
+      );
+    } else {
+      sections.push(
+        "Full patch withheld by configuration; file contents were not disclosed."
+      );
+    }
+
+    // Redaction runs before the caller caps the region, so a limit can never
+    // split a secret and leave a readable fragment behind.
+    return {
+      level,
+      status: "collected",
+      text: redact(sections.filter(Boolean).join("\n\n")),
+    };
+  } catch (error) {
+    return {
+      detail: error instanceof Error ? error.message : String(error),
+      level,
+      status: "failed",
+      text: "",
+    };
+  }
+};

package/src/outcomes.ts

@@ -0,0 +1,85 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type OutcomeAdoption = "followed" | "not-followed" | "unknown";
+export type OutcomeValidation = "passed" | "failed" | "not-run" | "unknown";
+export type OutcomeTrigger =
+  | "manual"
+  | "executor-requested"
+  | "repeated-tool-call";
+export const ADOPTIONS: OutcomeAdoption[] = [
+  "followed",
+  "not-followed",
+  "unknown",
+];
+export const VALIDATIONS: OutcomeValidation[] = [
+  "passed",
+  "failed",
+  "not-run",
+  "unknown",
+];
+export interface OutcomeRecord {
+  adoption: OutcomeAdoption;
+  adviceHash: string;
+  timestamp: string;
+  trigger: OutcomeTrigger;
+  v: 1;
+  validationStatus: OutcomeValidation;
+}
+const MAX_LOG_BYTES = 1024 * 1024;
+const statePath = () => join(getAgentDir(), "advisor-outcomes-salt");
+export const outcomeLogPath = () =>
+  join(getAgentDir(), "advisor-outcomes.jsonl");
+
+const salt = async () => {
+  const path = statePath();
+  try {
+    return await readFile(path);
+  } catch {
+    await mkdir(getAgentDir(), { mode: 0o700, recursive: true });
+    const value = randomBytes(32);
+    const temporary = `${path}.${process.pid}.${Date.now()}`;
+    await writeFile(temporary, value, { mode: 0o600 });
+    await rename(temporary, path);
+    await chmod(path, 0o600);
+    return value;
+  }
+};
+export const adviceDigest = (advice: string, key: Buffer) =>
+  createHmac("sha256", key).update(advice).digest("hex").slice(0, 16);
+
+/** Best-effort, global-only, minimal persistent telemetry. */
+export const appendOutcome = async (
+  record: Omit<OutcomeRecord, "adviceHash" | "timestamp" | "v"> & {
+    advice: string;
+  }
+) => {
+  const path = outcomeLogPath();
+  await mkdir(getAgentDir(), { mode: 0o700, recursive: true });
+  let previous = "";
+  try {
+    previous = await readFile(path, "utf8");
+  } catch {
+    /* new log */
+  }
+  const next: OutcomeRecord = {
+    adoption: record.adoption,
+    adviceHash: adviceDigest(record.advice, await salt()),
+    timestamp: new Date().toISOString(),
+    trigger: record.trigger,
+    v: 1,
+    validationStatus: record.validationStatus,
+  };
+  const line = `${JSON.stringify(next)}\n`;
+  const retained =
+    Buffer.byteLength(previous) + Buffer.byteLength(line) > MAX_LOG_BYTES
+      ? ""
+      : previous;
+  const temporary = `${path}.${process.pid}.${Date.now()}`;
+  await writeFile(temporary, retained + line, { mode: 0o600 });
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return next;
+};