pi-advisor-flow 0.2.4 → 0.2.7

package/src/config.ts

@@ -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[] = [
@@ -53,7 +59,11 @@ 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;
@@ -141,9 +151,21 @@ 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
@@ -160,9 +182,12 @@ 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,
@@ -170,6 +195,7 @@ export const getAdvisorSettings = () => ({
   toolPolicies: { ...advisorToolPoliciesRef },
   toolResultMaxBytes: advisorToolResultMaxBytesRef,
   toolResultMaxLines: advisorToolResultMaxLinesRef,
+  untrackedContent: advisorUntrackedContentRef,
 });
 
 export const splitRef = (ref: string): [string, string] => {
@@ -193,15 +219,19 @@ 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;
@@ -219,6 +249,8 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "advisorCustomInvocation",
   "advisorEffort",
   "advisorFailureGate",
+  "advisorGitContext",
+  "advisorGitContextMaxChars",
   "advisorHerdrIntegration",
   "advisorLoopThreshold",
   "advisorMaxCallsPerSession",
@@ -229,6 +261,8 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "advisorToolResultMaxBytes",
   "advisorToolResultMaxLines",
   "advisorRedactSecrets",
+  "advisorUntrackedContent",
+  "advisorOutcomeLogging",
   "advisorToolPolicies",
   "contextMaxChars",
   "executor",
@@ -247,6 +281,8 @@ const BOOLEAN_CONFIG_KEYS = [
   "alwaysOn",
   "advisorHerdrIntegration",
   "advisorRedactSecrets",
+  "advisorUntrackedContent",
+  "advisorOutcomeLogging",
 ] as const;
 const STRING_CONFIG_KEYS = [
   "executor",
@@ -347,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])) {
@@ -385,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;
 };
 
@@ -411,7 +462,11 @@ const resetDefaults = () => {
   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>(
@@ -501,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 => {
@@ -517,13 +583,14 @@ 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;
+const configCache = new Map<
+  string,
+  { config: AdvisorConfig; identity: string }
+>();
 
 /** Drops the parsed-configuration cache; the next load re-reads from disk. */
 export const resetConfigCache = () => {
-  configCache = undefined;
+  configCache.clear();
 };
 
 /**
@@ -542,34 +609,34 @@ const configIdentity = (path: string): string => {
 
 const readConfigCached = (path: string): AdvisorConfig => {
   const identity = configIdentity(path);
-  const cached = configCache;
-  if (cached && cached.path === path && cached.identity === identity) {
+  const cached = configCache.get(path);
+  if (cached?.identity === identity) {
     return cached.config;
   }
   const config = readConfig(path);
-  configCache = { config, identity, path };
+  configCache.set(path, { config, identity });
   return config;
 };
 
-export const loadConfig = (ctx: ExtensionContext) => {
+export const loadConfig = (_ctx: ExtensionContext) => {
   resetDefaults();
-  const path = configPaths(ctx).find(
-    (candidate): candidate is string =>
-      candidate !== null && existsSync(candidate)
-  );
-  if (!path) {
-    return null;
+  const global = join(getAgentDir(), "advisor.json");
+  const globalConfig = existsSync(global)
+    ? readConfigCached(global)
+    : undefined;
+  if (globalConfig) {
+    applyConfig(globalConfig);
   }
-  applyConfig(readConfigCached(path));
-  return path;
+  // Repository-controlled project configuration is never applied. Models,
+  // prompts, gates, budgets, disclosure, redaction, integrations, and consent
+  // remain under the user's global Pi configuration.
+  advisorOutcomeLoggingRef = globalConfig?.advisorOutcomeLogging === true;
+  return existsSync(global) ? global : null;
 };
 
-export const saveConfig = (ctx: ExtensionContext) => {
-  const project = join(ctx.cwd, CONFIG_DIR_NAME, "advisor.json");
-  const path =
-    ctx.isProjectTrusted() && existsSync(project)
-      ? project
-      : join(getAgentDir(), "advisor.json");
+/** Saves user-controlled configuration globally without outcome consent. */
+export const saveConfig = (_ctx: ExtensionContext) => {
+  const path = join(getAgentDir(), "advisor.json");
   let existing: Record<string, unknown> = {};
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -600,12 +667,15 @@ 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,
@@ -615,6 +685,26 @@ export const saveConfig = (ctx: ExtensionContext) => {
   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;
+};
+
 export const parseArgs = (args: string): string | undefined => {
   let nextExecutor = executorRef;
   let nextAdvisor = advisorRef;

package/src/conversation.ts

@@ -37,6 +37,8 @@ export const textFrom = (content: unknown): string =>
 const byteLength = (value: string) => Buffer.byteLength(value, "utf8");
 
 const REDACTION_MARKER = "[REDACTED SECRET]";
+const PEM_BEGIN_PATTERN = /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----/gi;
+const PEM_END_PATTERN = /-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/i;
 const SECRET_PATTERNS = [
   /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]*?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/gi,
   /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi,
@@ -46,9 +48,23 @@ const SECRET_PATTERNS = [
   /\b(?:aws_secret_access_key|aws_session_token)\s*[:=]\s*[^\s"'&,;)}\]]+/gi,
 ] as const;
 
+const redactUnterminatedPem = (value: string): string => {
+  const begins = [...value.matchAll(PEM_BEGIN_PATTERN)];
+  const lastBegin = begins.at(-1);
+  if (lastBegin?.index === undefined) {
+    return value;
+  }
+  const hasEnd = PEM_END_PATTERN.test(
+    value.slice(lastBegin.index + lastBegin[0].length)
+  );
+  return hasEnd
+    ? value
+    : `${value.slice(0, lastBegin.index)}${REDACTION_MARKER}`;
+};
+
 /** Redacts common credential forms locally; it is not a data-classification system. */
 export const redactSecrets = (value: string): string => {
-  let redacted = value;
+  let redacted = redactUnterminatedPem(value);
   for (const pattern of SECRET_PATTERNS) {
     redacted = redacted.replace(pattern, (_match, scheme) =>
       typeof scheme === "string"
@@ -59,6 +75,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;

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/herdr.ts

@@ -1,5 +1,6 @@
 import net from "node:net";
-import { advisorHerdrIntegrationRef } from "./config.js";
+import { getAdvisorSettings } from "./config.js";
+import { redactSecrets } from "./conversation.js";
 
 const SOURCE = "pi-advisor:advisor-activity";
 const BLOCK_SOURCE = "pi-advisor:advisor-block";
@@ -41,7 +42,7 @@ const isControlCharacter = (character: string) =>
   character <= "\u001f" || character === "\u007f";
 
 const cleanNotification = (value: string, max: number) =>
-  [...value]
+  [...redactSecrets(value)]
     .map((character) => (isControlCharacter(character) ? " " : character))
     .join("")
     .replace(/\s+/g, " ")
@@ -167,7 +168,7 @@ export class HerdrAdvisorBlock {
       return;
     }
     this.#blocked = true;
-    this.safeReport({ blocked: reason });
+    this.safeReport({ blocked: cleanNotification(reason, 200) });
   }
 
   clear() {
@@ -176,9 +177,8 @@ export class HerdrAdvisorBlock {
     if (!wasBlocked) {
       return;
     }
-    if (!this.enabled()) {
-      return;
-    }
+    // Clearing previously reported state is a de-escalation and must still be
+    // delivered if integration was disabled after the block was reported.
     try {
       this.report({
         id: `${BLOCK_SOURCE}:${nextSequence()}`,
@@ -218,7 +218,7 @@ export class HerdrAdvisorBlock {
 }
 
 export const notifyHerdrAdvisorFailure = (title: string, body: string) => {
-  if (!advisorHerdrIntegrationRef) {
+  if (!getAdvisorSettings().herdrIntegration) {
     return;
   }
   try {
@@ -230,9 +230,9 @@ export const notifyHerdrAdvisorFailure = (title: string, body: string) => {
 
 export const herdrAdvisorActivity = new HerdrAdvisorActivity(
   sendToHerdr,
-  () => advisorHerdrIntegrationRef
+  () => getAdvisorSettings().herdrIntegration
 );
 export const herdrAdvisorBlock = new HerdrAdvisorBlock(
   sendToHerdr,
-  () => advisorHerdrIntegrationRef
+  () => getAdvisorSettings().herdrIntegration
 );

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;
+};