pi-advisor-flow 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project are documented here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.9
+
+### Fixed
+
+- Preserved custom numeric values when stepping `/advisor-settings` controls instead of resetting off-preset budgets and disclosure caps.
+- Kept recorded session blocks enforced after `/advisor-off`, restored configuration after failed activation, and charged Advisor-call budgets only when consultation execution begins.
+- Kept conversation and repository disclosure within their configured caps and explicitly identified disabled repository context as withheld.
+- Made concurrent outcome records append safely with one exclusively initialized digest salt, and stopped superseded manual consultations from entering session summaries.
+- Preserved and ignored forward-compatible `advisor.json` fields with a warning, and made malformed configuration errors actionable in every Advisor command.
+- Isolated call budgets, repeated-action counters, and safety blocks between concurrent same-process sessions.
+- Kept the repository-context withheld warning visible when its disclosure budget is zero.
+
+## 0.2.8
+
+### Fixed
+
+- Advisor session blocks are reported to Herdr again. Herdr grants each pane a single lifecycle status authority, which for Pi is Herdr's own `herdr-agent-state` integration, and silently drops semantic state from any other source. The Advisor block now signals that integration over Pi's in-process event bus (`herdr:blocked`) instead of relying on display metadata alone, so a blocked pane shows `blocked` rather than `working`. Only the unblocked-to-blocked edge emits, because the listener refcounts; clears are always delivered.
+
 ## 0.2.7
 
 ### Security

package/README.md

@@ -8,17 +8,22 @@ A configurable second-opinion workflow for <a href="https://github.com/earendil-
 
 </div>
 
-This extension introduces a strategic "Executor/Advisor" workflow.
+`pi-advisor-flow` keeps one model focused on execution and makes a second, smarter model available for consequential decisions, stalled work, and final reviews. The Executor still owns the work. The Advisor challenges assumptions, exposes risks, and suggests verification steps without taking over or running tools.
 
-`pi-advisor-flow` keeps one model focused on execution and makes a second, smarter model available for consequential decisions, stalled work, and final reviews. The Executor still owns the work. The Advisor provides a concise review, answers questions and can provide help; it does not take over planning or run tools.
+The idea is simple: keep implementation on a fast model and borrow frontier reasoning only when decisions matter. [Read why this workflow is useful](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
 
-The concept is simple, keep implementation on a fast model, borrow frontier reasoning only when decisions actually matter. [Read more about Advisors here](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
+## Features
 
-## Install
+- **On-demand second opinions** through the `ask_advisor` tool or `/advisor-manual`.
+- **Configurable review gates** before plans, after repeated failures, and before declaring completion.
+- **Automatic loop detection** for repeated tool calls, with explicit proceed, revise, or blocked decisions.
+- **Separate model and reasoning controls** for the Executor and Advisor.
+- **Privacy controls** for conversation history, repository context, tool results, secret redaction, and outcome logging.
+- **Optional persistent activation, Simple mode, session summaries, and Herdr integration.**
 
-Requires Pi 0.80.7 or later. The extension installs no dependencies of its own; Pi supplies the modules it uses at runtime.
+## Install
 
-Install into your Pi agent environment:
+Current release: **0.2.9**. Requires Pi 0.80.7 or later. The extension installs no dependencies of its own; Pi supplies its runtime modules.
 
 ```bash
 # npm
@@ -27,197 +32,65 @@ pi install npm:pi-advisor-flow
 # GitHub
 pi install git:github.com/philipbrembeck/pi-advisor.git
 
-# local checkout, useful during development
+# local checkout
 pi install /path/to/pi-advisor
 ```
 
-Restart or reload Pi after installation, then run `/advisor` in a session.
+Restart or reload Pi after installation.
 
-## Start using it
+## Quick start
 
 1. Run `/advisor` to enable the flow and register `ask_advisor`.
 2. Run `/advisor-models` to choose the Executor and Advisor models.
-3. Run `/advisor-settings` to set Simple mode, persistent activation, context, gates, privacy controls, and output limits.
-
-Enable with models in one command when preferred:
-
-```text
-/advisor executor=anthropic/claude-sonnet-5 advisor=openai/gpt-5.6-sol
-```
-
-`/advisor contextMaxChars=30000` sets the reconstructed-context limit for the current session. Use `0` for no history. The `ALL` option in settings represents the complete current branch and is still subject to the Advisor model's context limit.
-
-## Commands
-
-| Command                   | Purpose                                                                                                                                         |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/advisor`                | Enable the flow, select the configured Executor, and register `ask_advisor`. Accepts `executor=`, `advisor=`, and `contextMaxChars=` overrides. |
-| `/advisor-manual [focus]` | Start a parallel Advisor consultation without interrupting the current Executor turn.                                                           |
-| `/advisor-models`         | Choose Executor and Advisor models plus their reasoning effort.                                                                                 |
-| `/advisor-settings`       | Open all Advisor settings in one keyboard-navigable screen.                                                                                     |
-| `/advisor-off`            | Disable the flow and remove `ask_advisor` from the active session.                                                                              |
-
-### `ask_advisor`
-
-The Executor calls `ask_advisor({})` for a general review of the current task and reconstructed conversation. It can pass a `question` for a targeted review, or a concise `draft` for plan and completion reviews. A draft should name proposed work, validation, and remaining risks; it is an unverified claim, not evidence.
-
-Successful calls return an opaque `adviceId`. When global outcome logging is enabled, the Executor may voluntarily call `record_advisor_outcome` once with that ID, an adoption value, and a final validation status.
-
-Use the Advisor after the Executor has investigated and formed a candidate direction. It is intended to challenge assumptions, expose risks, and confirm the next verification step—not to replace the Executor's work.
-
-Normal consultations preserve the provider's final Markdown and never block execution. When the Advisor has no material concern or recommendation, it may begin with the exact first line `Verdict: sound`; Pi renders that response with the static `◆ ADVISOR · SOUND` header, for both `ask_advisor` results and `/advisor-manual`.
+3. Run `/advisor-settings` to configure review gates, context, privacy, and limits.
 
-## Automatic loop gate
+Unknown fields in `advisor.json` are preserved for forward compatibility and reported as non-blocking warnings. Invalid recognized values remain errors, and Advisor commands show the configuration problem without crashing their handlers.
 
-The optional loop gate detects consecutive calls with the same normalized tool signature. By default, it consults the Advisor after three repeats.
-
-Unlike ordinary consultations, a loop-gate reply must start with exactly one decision header:
+You can also enable the flow and select both models at once:
 
 ```text
-Decision: proceed
-Decision: revise
-Decision: blocked
-```
-
-| Decision  | Effect                                              |
-| --------- | --------------------------------------------------- |
-| `proceed` | Reset the repeat counter and allow the tool action. |
-| `revise`  | Block the repeated tool action.                     |
-| `blocked` | Apply the configured gate-failure policy.           |
-
-Malformed, missing, duplicate, or contradictory decisions are gate failures. The same policy also applies when the Advisor is unavailable or the shared call budget is exhausted.
-
-| Failure mode              | Effect                              |
-| ------------------------- | ----------------------------------- |
-| `block-session` (default) | Block the session.                  |
-| `block-tool`              | Block only the current tool action. |
-| `warn-and-continue`       | Show a warning and continue.        |
-
-| Condition                                                | `block-session` | `block-tool`      | `warn-and-continue` |
-| -------------------------------------------------------- | --------------- | ----------------- | ------------------- |
-| Advisor unavailable or timed out                         | Block session   | Block tool action | Warn and continue   |
-| Missing, malformed, duplicate, or contradictory decision | Block session   | Block tool action | Warn and continue   |
-| Shared budget exhausted                                  | Block session   | Block tool action | Warn and continue   |
-| `Decision: blocked`                                      | Block session   | Block tool action | Warn and continue   |
-
-`advisorBlockOnBlocked` controls whether a session block immediately aborts the active run. It never turns a session block into a tool-only block.
-
-## Settings and configuration
-
-`/advisor-models` and `/advisor-settings` save to global `advisor.json` in the Pi agent directory. Repository-controlled project `advisor.json` files are not applied; models, prompts, gates, budgets, disclosure, redaction, integrations, and consent remain under the user's global configuration.
-
-All fields are optional. This example shows the available settings and their normal defaults:
-
-```json
-{
-  "executor": "openai/gpt-5.6-luna",
-  "advisor": "anthropic/claude-fable-5",
-  "executorEffort": "medium",
-  "advisorEffort": "xhigh",
-  "contextMaxChars": 25000,
-
-  "advisorPlanGate": true,
-  "advisorFailureGate": true,
-  "advisorCompletionGate": true,
-  "advisorCustomInvocation": "before changing a production deployment",
-  "advisorCollapseResponses": false,
-
-  "advisorAutoLoopGate": true,
-  "advisorLoopThreshold": 3,
-  "advisorMaxCallsPerSession": 5,
-  "advisorBlockOnBlocked": true,
-  "gateFailureMode": "block-session",
-
-  "advisorSessionSummary": false,
-  "advisorGitContext": "summary",
-  "advisorGitContextMaxChars": 20000,
-  "simpleMode": false,
-  "alwaysOn": false,
-  "advisorHerdrIntegration": true,
-  "advisorToolResultMaxLines": 2000,
-  "advisorToolResultMaxBytes": 51200,
-
-  "advisorRedactSecrets": false,
-  "advisorUntrackedContent": false,
-  "advisorOutcomeLogging": false,
-  "advisorToolPolicies": {
-    "bash": "summary",
-    "deploy": "exclude"
-  }
-}
+/advisor executor=anthropic/claude-sonnet-5 advisor=openai/gpt-5.6-sol
 ```
 
-### Simple mode and persistent activation
-
-- `simpleMode` defaults to `false`. When enabled, `ask_advisor` and `/advisor-manual` remain available for voluntary second opinions, while plan/failure/completion rules, loop gates, blocking, call budgets, and session summaries are disabled. Context limits, result caps, redaction, and tool disclosure policies still apply.
-- `alwaysOn` defaults to `false`. When enabled, Pi restores the configured Executor and activates `ask_advisor` for new, resumed, forked, and reloaded sessions. While the Advisor flow is active, an explicit `/model` selection becomes the persisted Executor for the next activation; a model restored with a session does not change the saved Executor. `/advisor-off` turns `alwaysOn` off so the flow stays disabled in later sessions.
-- In Simple mode, settings keeps the Context window/history slider alongside Simple mode and Always on; advanced values remain saved and take effect when Simple mode is disabled.
-
-### Repository context
-
-- `advisorGitContext` defaults to `summary`. It controls how much of the working tree reaches the Advisor:
-  - `off` sends no repository information.
-  - `summary` sends changed file names, change status, and line counts. It never sends file contents.
-  - `full` additionally sends the patch.
-- Changes are measured against the last commit and cover staged and unstaged work. Untracked files are always listed by name only; their contents are never sent by `gitContext: full`.
-- `advisorUntrackedContent` defaults to false. When enabled, `includeUntracked` can attach only exact named, repository-relative, untracked regular files. Files are redacted and capped before egress; sibling files remain withheld.
-- `advisorGitContextMaxChars` defaults to `20000`. Repository context may claim its own cap or half of `contextMaxChars`, whichever is smaller, so it cannot crowd out the conversation.
-- The Executor may pass `gitContext` to `ask_advisor` as `none`, `summary`, or `full`. `advisorGitContext` is the ceiling: a larger request is narrowed to the configured level and the Advisor is told that a fuller view was withheld, so it does not claim verification it could not perform.
-- `summary` deliberately excludes diff hunk headers. Git derives those from surrounding file content, so a hunk header can reproduce a line the change never touched, including a credential.
-- Redaction runs before the region is capped, and repository content is labelled as untrusted data in the request. Paths and patch text are escaped so a crafted path cannot close the region early and have the remainder read as instructions.
-- File names themselves can be sensitive. `summary` withholds file contents, not file names; use `off` when names must not leave the machine.
-- Collection shares a single overall time budget across its git commands and degrades to a stated failure rather than implying a clean tree.
-
-### Project preferences and outcomes
+## How it works
 
-In a trusted project only, `.pi/advisor-preferences.md` may provide a short local brief. It is never written by pi-advisor, is treated as lower-priority untrusted text, and is redacted/capped before egress. Symlinks, unreadable files, and paths outside the project are ignored.
+1. The Executor investigates the task and forms its own candidate direction.
+2. For a consequential decision, stalled attempt, or final review, it calls `ask_advisor` with the reconstructed conversation and allowed repository context.
+3. The Advisor returns a concise review. It may challenge assumptions, identify risks, or recommend the next verification step.
+4. The Executor decides what to adopt, performs the work, and validates the result.
 
-`advisorOutcomeLogging` defaults to false and is global-only: a project config cannot enable it. When enabled, `~/.pi/agent/advisor-outcomes.jsonl` stores bounded rotating JSONL records with only a version, timestamp, salted truncated advice digest, trigger, adoption, and validation status. It stores no prompt, advice, paths, tool output, repository data, session ID, or advice ID.
+A normal consultation never blocks execution. The optional automatic loop gate is different: it evaluates repeated tool calls and applies the configured failure policy when the Advisor says to revise, reports a block, is unavailable, or returns an invalid decision.
 
-### Context and limits
+Successful calls return an opaque `adviceId`. If global outcome logging is enabled, the Executor can call `record_advisor_outcome` once to record whether the advice was adopted and whether final validation passed.
 
-- `contextMaxChars` defaults to `15000`. It preserves complete semantic entries and adds an omission marker rather than splitting a message.
-- Set `contextMaxChars` to `0` to omit reconstructed history. `9007199254740991` is the persisted value for `ALL`.
-- Tool results default to Pi's `2000` lines and `50 KiB` limits. Oversized results preserve their beginning and end with an omission marker.
-- `advisorLoopThreshold` is an integer of at least `2`; its default is `3`.
-- Omit `advisorMaxCallsPerSession` for an unlimited shared budget. Otherwise it must be a non-negative safe integer.
-
-### Privacy controls
-
-Advisor context can contain user messages, tool calls, and tool results. Configure disclosure deliberately:
-
-- `advisorRedactSecrets` defaults to `false`. When enabled, pi-advisor locally redacts common credential patterns before including context in an Advisor request.
-- `advisorToolPolicies` matches an **exact tool name**. Each tool may use `full`, `summary`, or `exclude`.
-  - `full` includes the call arguments and capped result output.
-  - `summary` omits call arguments and result output but includes result status and size metadata.
-  - `exclude` omits both call details and output.
-- Tools not listed in `advisorToolPolicies`, including custom and newly added tools, use `full` for backward compatibility.
-
-Redaction and output limits reduce accidental disclosure; they are not a data-classification system and cannot guarantee every secret is found. Use tool policies for content that must not be sent to the Advisor.
+## Commands
 
-### Session summary and Herdr
+| Command | Purpose |
+| --- | --- |
+| `/advisor` | Enable the flow and optionally override the Executor, Advisor, or context limit. |
+| `/advisor-manual [focus]` | Start a parallel consultation without interrupting the current Executor turn. |
+| `/advisor-models` | Choose both models and their reasoning effort. |
+| `/advisor-settings` | Configure behavior, context, gates, privacy, and output limits. |
+| `/advisor-off` | Disable the flow and turn off persistent activation. |
 
-The optional Session Advisor Summary defaults to off. When enabled, it is local and in-memory only, appears after a non-blocked settled run, and is never persisted.
+The Executor calls `ask_advisor({})` for a general review. It can pass a targeted `question` or a concise `draft` describing proposed work, validation, and remaining risks. Draft claims give the Advisor review context; they are not verification evidence.
 
-It distinguishes regular Markdown advice from gate decisions and records the trigger, model, usage/cost when available, failures, budget, and execution effect.
+## What gets sent to the Advisor
 
-[Herdr](https://github.com/ogulcancelik/herdr) integration is enabled by default. It reports Advisor activity and a bounded, redacted blocked-state summary through Herdr's metadata paths; disable it with `advisorHerdrIntegration`. Previously reported state is still cleared when integration is disabled.
+Advisor context can include user messages, tool calls, tool results, and repository information. Secret redaction is off by default, and tools without an explicit disclosure policy default to full context. Review the privacy settings before using the extension with sensitive work.
 
-## Development
+Repository context is configurable from no access through changed-file summaries to a capped patch. When context is disabled or its budget is zero, the Advisor is told it was withheld rather than shown an apparently clean tree. Untracked file contents require a separate explicit opt-in.
 
-```bash
-git clone git@github.com:philipbrembeck/pi-advisor.git
-cd pi-advisor
-bun install
+## Documentation
 
-bun test
-bun run typecheck
-bun run lint
-```
+- [Configuration and automatic loop gates](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/configuration.md)
+- [Privacy and data handling](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/privacy.md)
+- [Development](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/development.md)
+- [Documentation index](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/README.md)
 
 ## Links
 
-- [MIT LICENSE](LICENSE)
+- [MIT License](LICENSE)
 - [Changelog](CHANGELOG.md)
 - [npm package](https://www.npmjs.com/package/pi-advisor-flow)
 - [Why use an Advisor flow?](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need)

package/extensions/index.ts

@@ -1,5 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerCommands } from "../src/commands.js";
+import { setHerdrBlockedEmitter } from "../src/herdr.js";
+import { AdvisorSessionState } from "../src/session-state.js";
 import {
   consultAdvisor as consultAdvisorImplementation,
   parseAutomaticDecision as parseAutomaticDecisionImplementation,
@@ -28,6 +30,10 @@ export const runAdvisorGate = (
 ) => runAdvisorGateImplementation(...args);
 
 export default function (pi: ExtensionAPI) {
-  registerAdvisorTool(pi);
-  registerCommands(pi);
+  const sessionState = new AdvisorSessionState();
+  setHerdrBlockedEmitter((active, label) =>
+    pi.events.emit("herdr:blocked", { active, label })
+  );
+  registerAdvisorTool(pi, sessionState);
+  registerCommands(pi, { sessionState });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "author": "Philip Brembeck",
   "repository": {
     "type": "git",

package/src/commands.ts

@@ -9,6 +9,7 @@ import {
   advisorMaxCallsPerSessionRef,
   advisorRef,
   alwaysOnRef,
+  contextMaxCharsRef,
   executorEffortRef,
   executorRef,
   getAdvisorSettings,
@@ -47,10 +48,11 @@ import {
   splitRef,
 } from "./config.js";
 import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "./herdr.js";
+import type { AdvisorSessionState } from "./session-state.js";
 import {
   adviceForDisplay,
-  advisorSessionState,
   consultAdvisor,
+  advisorSessionState as defaultAdvisorSessionState,
   hasSoundVerdict,
   renderAdvisorCallBox,
   renderAdvisorResponseHeader,
@@ -138,8 +140,13 @@ const findConfiguredModel = (ctx: ExtensionContext, ref: string) => {
 
 export const registerCommands = (
   pi: ExtensionAPI,
-  dependencies: { consult?: ManualConsult } = {}
+  dependencies: {
+    consult?: ManualConsult;
+    sessionState?: AdvisorSessionState;
+  } = {}
 ) => {
+  const advisorSessionState =
+    dependencies.sessionState ?? defaultAdvisorSessionState;
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
   const requestAdvisor =
     dependencies.consult ??
@@ -155,15 +162,15 @@ export const registerCommands = (
     herdrAdvisorActivity.start();
     return requestAdvisor(ctx, question, controller.signal)
       .then(({ markdown }) => {
+        if (controller.signal.aborted) {
+          return;
+        }
         advisorSessionState.recordInvocation({
           executionEffect: "continued",
           kind: "markdown",
           model: advisorRef,
           trigger: "manual",
         });
-        if (controller.signal.aborted) {
-          return;
-        }
         pi.sendMessage(
           {
             content: `Manual Advisor consultation${question ? ` (${question})` : ""}:\n\n${markdown}`,
@@ -232,19 +239,48 @@ export const registerCommands = (
     return {};
   };
 
+  const loadCommandConfig = (ctx: ExtensionContext) => {
+    try {
+      loadConfig(ctx);
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      notify(
+        ctx,
+        `Advisor command could not load configuration: ${message} Fix advisor.json and retry.`,
+        "error"
+      );
+      return false;
+    }
+  };
+
   const activateAdvisor = async (
     args: string,
     ctx: ExtensionContext,
     announce = true
   ) => {
-    loadConfig(ctx);
+    if (!loadCommandConfig(ctx)) {
+      return;
+    }
+    const previous = {
+      advisor: advisorRef,
+      contextMaxChars: contextMaxCharsRef,
+      executor: executorRef,
+    };
+    const restoreRefs = () => {
+      setAdvisorRef(previous.advisor);
+      setContextMaxCharsRef(previous.contextMaxChars);
+      setExecutorRef(previous.executor);
+    };
     const argumentError = parseArgs(args);
     if (argumentError) {
+      restoreRefs();
       notify(ctx, argumentError, "error");
       return;
     }
     const { error } = await resolveActivationModels(ctx);
     if (error) {
+      restoreRefs();
       notify(ctx, error, "error");
       return;
     }
@@ -356,7 +392,9 @@ export const registerCommands = (
     description:
       "Consult the Advisor in parallel; accepts an optional focused question and fans its response out to the Executor",
     handler: (args, ctx) => {
-      loadConfig(ctx);
+      if (!loadCommandConfig(ctx)) {
+        return Promise.resolve();
+      }
       if (
         !(
           isSimpleMode() ||
@@ -396,8 +434,7 @@ export const registerCommands = (
     description:
       "Select and persist the Executor and Advisor models with reasoning levels",
     handler: async (_args, ctx) => {
-      loadConfig(ctx);
-      if (!ctx.hasUI) {
+      if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
         return;
       }
       const refs = ctx.modelRegistry
@@ -475,8 +512,7 @@ export const registerCommands = (
     description: "Configure Advisor context and reasoning effort",
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one settings form maps every persisted control.
     handler: async (_args, ctx) => {
-      loadConfig(ctx);
-      if (!ctx.hasUI) {
+      if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
         return;
       }
 

package/src/config.ts

@@ -305,16 +305,10 @@ const invalidConfigValue = (
   );
 };
 
-const validateKnownKeys = (config: ConfigRecord, path: string) => {
-  const unknownKeys = Object.keys(config).filter(
+const unknownConfigKeys = (config: ConfigRecord) =>
+  Object.keys(config).filter(
     (key) => !CONFIG_KEYS.has(key as keyof AdvisorConfig)
   );
-  if (unknownKeys.length > 0) {
-    throw new TypeError(
-      `Invalid advisor configuration at ${path}: unknown key(s) ${unknownKeys.map((key) => JSON.stringify(key)).join(", ")}. Remove them or upgrade pi-advisor.`
-    );
-  }
-};
 
 const validateStringValues = (config: ConfigRecord, path: string) => {
   for (const key of STRING_CONFIG_KEYS) {
@@ -406,7 +400,6 @@ export const validateConfig = (
     );
   }
   const config = value as ConfigRecord;
-  validateKnownKeys(config, path);
   validateStringValues(config, path);
   validateBooleanValues(config, path);
   validateNumericValues(config, path);
@@ -587,10 +580,12 @@ 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();
 };
 
 /**
@@ -626,6 +621,19 @@ export const loadConfig = (_ctx: ExtensionContext) => {
     : undefined;
   if (globalConfig) {
     applyConfig(globalConfig);
+    const unknownKeys = unknownConfigKeys(globalConfig as ConfigRecord);
+    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

package/src/conversation.ts

@@ -288,28 +288,41 @@ const selectRecentEntries = (entries: string[], maxChars: number): string => {
   if (joined.length <= maxChars || maxChars === Number.MAX_SAFE_INTEGER) {
     return joined;
   }
+  const newestTruncated = "[Newest entry truncated]";
+  if (entries.length === 1) {
+    const prefix = `${newestTruncated}${separator}`;
+    return `${prefix}${entries[0].slice(0, Math.max(0, maxChars - prefix.length))}`.slice(
+      0,
+      maxChars
+    );
+  }
   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 entry = entries[index];
+    const candidateCount = selected.length + 1;
+    const omitted = entries.length - candidateCount;
+    const marker = `[Older context omitted: ${omitted} complete entr${omitted === 1 ? "y" : "ies"}]`;
     const candidateLength =
       selectedLength +
       entry.length +
-      (selected.length === 0 ? 0 : separator.length);
-    if (candidateLength <= maxChars || selected.length === 0) {
-      selected.unshift(entry);
-      selectedLength = candidateLength;
-    } else {
+      (selected.length > 0 ? separator.length : 0);
+    if (marker.length + separator.length + candidateLength > maxChars) {
       break;
     }
+    selected.unshift(entry);
+    selectedLength = candidateLength;
   }
-  const omitted = entries.length - selected.length;
-  const suffix = selected.length
-    ? `${separator}${selected.join(separator)}`
-    : "";
-  return `[Older context omitted: ${omitted} complete entr${omitted === 1 ? "y" : "ies"}]${suffix}`;
+  const omitted = entries.length - Math.max(1, selected.length);
+  const marker = `[Older context omitted: ${omitted} complete entr${omitted === 1 ? "y" : "ies"}]`;
+  if (selected.length > 0) {
+    return `${marker}${separator}${selected.join(separator)}`;
+  }
+  const prefix = `${marker}${separator}${newestTruncated}${separator}`;
+  return `${prefix}${entries.at(-1)?.slice(0, Math.max(0, maxChars - prefix.length)) ?? ""}`.slice(
+    0,
+    maxChars
+  );
 };
 
 export const recentConversation = (

package/src/git.ts

@@ -60,8 +60,12 @@ export const capRepositoryContext = (value: string, maxChars: number) => {
   if (value.length <= maxChars) {
     return { text: value, truncated: false };
   }
+  const contentChars = Math.max(0, maxChars - TRUNCATION_NOTICE.length);
   return {
-    text: `${value.slice(0, Math.max(0, maxChars - TRUNCATION_NOTICE.length))}${TRUNCATION_NOTICE}`,
+    text:
+      maxChars < TRUNCATION_NOTICE.length
+        ? TRUNCATION_NOTICE.slice(0, maxChars)
+        : `${value.slice(0, contentChars)}${TRUNCATION_NOTICE}`,
     truncated: true,
   };
 };

package/src/herdr.ts

@@ -38,6 +38,25 @@ export interface HerdrNotificationRequest {
 export type HerdrRequest = HerdrMetadataRequest | HerdrNotificationRequest;
 type Report = (request: HerdrRequest) => void;
 
+// Herdr only accepts semantic state from the pane's lifecycle authority, which
+// for pi is herdr's own herdr-agent-state extension (source "herdr:pi"). Socket
+// reports from any other source are dropped, so the blocked state has to be
+// signalled through the in-process pi event bus that integration listens on.
+type BlockedEmitter = (active: boolean, label: string) => void;
+let emitBlocked: BlockedEmitter | undefined;
+
+export const setHerdrBlockedEmitter = (emitter: BlockedEmitter | undefined) => {
+  emitBlocked = emitter;
+};
+
+const safeEmitBlocked = (active: boolean, label = "Advisor blocked") => {
+  try {
+    emitBlocked?.(active, label);
+  } catch {
+    /* Herdr is optional. */
+  }
+};
+
 const isControlCharacter = (character: string) =>
   character <= "\u001f" || character === "\u007f";
 
@@ -167,8 +186,14 @@ export class HerdrAdvisorBlock {
     if (!this.enabled()) {
       return;
     }
+    const label = cleanNotification(reason, 200);
+    const wasBlocked: boolean = this.#blocked;
+    if (!wasBlocked) {
+      // The listener refcounts, so only the false → true edge may emit.
+      safeEmitBlocked(true, label);
+    }
     this.#blocked = true;
-    this.safeReport({ blocked: cleanNotification(reason, 200) });
+    this.safeReport({ blocked: label });
   }
 
   clear() {
@@ -179,6 +204,7 @@ export class HerdrAdvisorBlock {
     }
     // Clearing previously reported state is a de-escalation and must still be
     // delivered if integration was disabled after the block was reported.
+    safeEmitBlocked(false);
     try {
       this.report({
         id: `${BLOCK_SOURCE}:${nextSequence()}`,

package/src/outcomes.ts

@@ -1,5 +1,15 @@
 import { createHmac, randomBytes } from "node:crypto";
-import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import {
+  appendFile,
+  chmod,
+  link,
+  mkdir,
+  open,
+  readFile,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
@@ -35,18 +45,76 @@ export const outcomeLogPath = () =>
 
 const salt = async () => {
   const path = statePath();
-  try {
-    return await readFile(path);
-  } catch {
-    await mkdir(getAgentDir(), { mode: 0o700, recursive: true });
+  await mkdir(getAgentDir(), { mode: 0o700, recursive: true });
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    try {
+      // biome-ignore lint/performance/noAwaitInLoops: contenders retry sequentially until one salt is atomically published.
+      const existing = await readFile(path);
+      if (existing.length === 32) {
+        return existing;
+      }
+      // Recover a salt file left incomplete by an interrupted older writer.
+      await unlink(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw error;
+      }
+    }
     const value = randomBytes(32);
-    const temporary = `${path}.${process.pid}.${Date.now()}`;
+    const temporary = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.${attempt}`;
     await writeFile(temporary, value, { mode: 0o600 });
-    await rename(temporary, path);
-    await chmod(path, 0o600);
-    return value;
+    try {
+      await link(temporary, path);
+      return value;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+    } finally {
+      await unlink(temporary).catch(() => undefined);
+    }
+  }
+  throw new Error("Advisor outcome salt initialization did not complete.");
+};
+const sameFile = (
+  left: { dev: number | bigint; ino: number | bigint },
+  right: { dev: number | bigint; ino: number | bigint }
+) => left.dev === right.dev && left.ino === right.ino;
+
+const withOutcomeLock = async <T>(run: () => Promise<T>): Promise<T> => {
+  const lockPath = `${outcomeLogPath()}.lock`;
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    try {
+      // biome-ignore lint/performance/noAwaitInLoops: lock acquisition must retry sequentially across processes.
+      const lock = await open(lockPath, "wx", 0o600);
+      const identity = await lock.stat();
+      try {
+        return await run();
+      } finally {
+        await lock.close();
+        const current = await stat(lockPath).catch(() => undefined);
+        if (current && sameFile(identity, current)) {
+          await unlink(lockPath).catch(() => undefined);
+        }
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      const observed = await stat(lockPath).catch(() => undefined);
+      if (observed && Date.now() - observed.mtimeMs > 30_000) {
+        const current = await stat(lockPath).catch(() => undefined);
+        if (current && sameFile(observed, current)) {
+          await unlink(lockPath).catch(() => undefined);
+        }
+        continue;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
   }
+  throw new Error("Timed out waiting to append an Advisor outcome.");
 };
+
 export const adviceDigest = (advice: string, key: Buffer) =>
   createHmac("sha256", key).update(advice).digest("hex").slice(0, 16);
 
@@ -58,12 +126,6 @@ export const appendOutcome = async (
 ) => {
   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()),
@@ -73,13 +135,21 @@ export const appendOutcome = async (
     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);
+  await withOutcomeLock(async () => {
+    const currentBytes = await stat(path)
+      .then((value) => value.size)
+      .catch((error: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") {
+          return 0;
+        }
+        throw error;
+      });
+    if (currentBytes + Buffer.byteLength(line) > MAX_LOG_BYTES) {
+      await writeFile(path, line, { encoding: "utf8", mode: 0o600 });
+    } else {
+      await appendFile(path, line, { encoding: "utf8", mode: 0o600 });
+    }
+    await chmod(path, 0o600);
+  });
   return next;
 };

package/src/tools.ts

@@ -141,6 +141,8 @@ export const gitContextNote = (
     return `Repository context was limited to "${allowed}" by user configuration; a fuller view was requested but withheld.`;
   }
   switch (result.status) {
+    case "disabled":
+      return "Repository context was disabled or had no disclosure budget; it was withheld. Do not assume the working tree is clean.";
     case "no-changes":
       return "The working tree has no uncommitted changes.";
     case "not-a-repository":
@@ -157,6 +159,20 @@ const LEVEL_WITHHELD: Record<string, boolean> = {
   "no-changes": false,
 };
 
+export const advisorRepositoryContext = (
+  result: GitContextResult,
+  requested: GitContextLevel,
+  allowed: GitContextLevel,
+  budget: number
+) => {
+  const note = gitContextNote(result, requested, allowed);
+  const payload = capRepositoryContext(
+    escapeRepositoryText(result.text),
+    budget
+  ).text;
+  return [note, payload].filter(Boolean).join("\n\n");
+};
+
 /**
  * The conversation boundary for outgoing Advisor requests. Repository context is
  * the only other egress path; both are assembled by advisorMessageText and both
@@ -433,11 +449,14 @@ const collectAdvisorResponse = async (
   );
   // The note is placed first so a cap can never drop the statement that the
   // Advisor's view of the repository is limited.
-  const note = gitContextNote(changes, gitContext ?? allowed, level);
-  const changeText = capRepositoryContext(
-    [note, escapeRepositoryText(changes.text)].filter(Boolean).join("\n\n"),
+  // The disclosure warning is control metadata, not repository payload. Keep it
+  // outside the zero-byte Git budget so disabling disclosure cannot erase it.
+  const changeText = advisorRepositoryContext(
+    changes,
+    gitContext ?? allowed,
+    level,
     gitBudget
-  ).text;
+  );
   // Repository context spends part of the shared budget, so a large patch
   // cannot silently push the conversation past the model's context window.
   const conversation = advisorRequestConversation(
@@ -668,7 +687,6 @@ const reserveAdvisorCall = (
     notifyHerdrAdvisorFailure("Advisor budget exhausted", message);
     return { block: true, reason: message };
   }
-  session.consumeCall();
   reservedCalls.add(event.toolCallId);
   return {};
 };
@@ -934,8 +952,10 @@ const renderAdvisorResult = (
   return box;
 };
 
-export const registerAdvisorTool = (pi: ExtensionAPI) => {
-  const session = advisorSessionState;
+export const registerAdvisorTool = (
+  pi: ExtensionAPI,
+  session: AdvisorSessionState = advisorSessionState
+) => {
   const reservedCalls = new Set<string>();
 
   pi.registerMessageRenderer?.(
@@ -1021,16 +1041,16 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
   });
 
   pi.on("tool_call", (event, ctx) => {
-    if (!pi.getActiveTools().includes("ask_advisor")) {
-      return;
-    }
-    loadConfig(ctx);
-    if (!isSimpleMode() && session.blocked) {
+    if (session.blocked) {
       return {
         block: true,
         reason: session.blockedReason ?? "Advisor session is blocked.",
       };
     }
+    if (!pi.getActiveTools().includes("ask_advisor")) {
+      return;
+    }
+    loadConfig(ctx);
     const reservation = reserveAdvisorCall(event, ctx, session, reservedCalls);
     if (event.toolName === "ask_advisor") {
       return reservation;
@@ -1039,6 +1059,9 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
   });
 
   pi.on("agent_settled", (_event, ctx) => {
+    // Any reservation still present never reached execute (for example because
+    // another handler blocked it or the turn was aborted).
+    reservedCalls.clear();
     if (isSimpleMode() || session.blocked || !advisorSessionSummaryRef) {
       return;
     }
@@ -1057,7 +1080,8 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
     description:
       "Consult the on-demand Advisor model for strategic guidance. Call with an empty object for a contextual review; attach an optional draft for concrete plan or completion review.",
     async execute(_id, params, signal, onUpdate, ctx) {
-      if (!(reservedCalls.delete(_id) || isSimpleMode())) {
+      reservedCalls.delete(_id);
+      if (!isSimpleMode()) {
         if (!session.canConsult(advisorMaxCallsPerSessionRef)) {
           throw new Error("Advisor call budget exhausted for this session.");
         }

package/src/ui.ts

@@ -24,6 +24,18 @@ interface SearchableModelSelectorOptions {
   title: string;
   tui: RenderRequester;
 }
+const stepNumericPreset = (
+  current: number,
+  presets: number[],
+  direction: number
+) => {
+  const values = presets.includes(current)
+    ? presets
+    : [...presets, current].sort((a, b) => a - b);
+  const index = values.indexOf(current);
+  return values[Math.max(0, Math.min(values.length - 1, index + direction))];
+};
+
 interface AdvisorSettingsSelectorOptions {
   effortLevels: string[];
   initial: AdvisorSettings;
@@ -304,14 +316,24 @@ export class AdvisorSettingsSelector implements Component, Focusable {
     this.editingCustom = false;
     this.editingPolicies = false;
     this.policiesError = undefined;
-    this.options = options;
     // Retain every advanced value even when Simple mode hides its controls.
     this.settings = { ...options.initial };
-    this.contextIndex = Math.max(
-      0,
-      options.presets.findIndex(
-        (preset) => preset.value === this.settings.contextMaxChars
-      )
+    const configuredContext = this.settings.contextMaxChars;
+    const presets = options.presets.some(
+      (preset) => preset.value === configuredContext
+    )
+      ? [...options.presets]
+      : [
+          ...options.presets,
+          {
+            description: "Custom configured value",
+            label: String(configuredContext),
+            value: configuredContext,
+          },
+        ].sort((a, b) => a.value - b.value);
+    this.options = { ...options, presets };
+    this.contextIndex = presets.findIndex(
+      (preset) => preset.value === configuredContext
     );
     this.effortIndex = Math.max(
       0,
@@ -746,6 +768,7 @@ export class AdvisorSettingsSelector implements Component, Focusable {
     tui.requestRender();
   }
 
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one keyboard dispatcher maps each settings row to its bounded adjustment.
   private adjust(direction: number): void {
     switch (this.selectedRowId()) {
       case "simpleMode":
@@ -808,11 +831,14 @@ export class AdvisorSettingsSelector implements Component, Focusable {
         );
         break;
       case "maxCallsPerSession": {
-        const values = [undefined, 0, 1, 2, 3, 5, 10, 25, 50];
-        const index = Math.max(
-          0,
-          values.indexOf(this.settings.maxCallsPerSession)
-        );
+        const current = this.settings.maxCallsPerSession;
+        const numeric = [0, 1, 2, 3, 5, 10, 25, 50];
+        const sorted =
+          current === undefined || numeric.includes(current)
+            ? numeric
+            : [...numeric, current].sort((a, b) => a - b);
+        const values: (number | undefined)[] = [undefined, ...sorted];
+        const index = values.indexOf(current);
         this.settings.maxCallsPerSession =
           values[Math.max(0, Math.min(values.length - 1, index + direction))];
         break;
@@ -865,33 +891,27 @@ export class AdvisorSettingsSelector implements Component, Focusable {
         break;
       }
       case "gitContextMaxChars": {
-        const values = [0, 5000, 10_000, 20_000, 50_000, 100_000];
-        const index = Math.max(
-          0,
-          values.indexOf(this.settings.gitContextMaxChars ?? 20_000)
+        this.settings.gitContextMaxChars = stepNumericPreset(
+          this.settings.gitContextMaxChars ?? 20_000,
+          [0, 5000, 10_000, 20_000, 50_000, 100_000],
+          direction
         );
-        this.settings.gitContextMaxChars =
-          values[Math.max(0, Math.min(values.length - 1, index + direction))];
         break;
       }
       case "toolResultMaxLines": {
-        const values = [0, 500, 1000, 2000, 5000, 10_000];
-        const index = Math.max(
-          0,
-          values.indexOf(this.settings.toolResultMaxLines ?? 2000)
+        this.settings.toolResultMaxLines = stepNumericPreset(
+          this.settings.toolResultMaxLines ?? 2000,
+          [0, 500, 1000, 2000, 5000, 10_000],
+          direction
         );
-        this.settings.toolResultMaxLines =
-          values[Math.max(0, Math.min(values.length - 1, index + direction))];
         break;
       }
       case "toolResultMaxBytes": {
-        const values = [0, 10 * 1024, 50 * 1024, 100 * 1024, 500 * 1024];
-        const index = Math.max(
-          0,
-          values.indexOf(this.settings.toolResultMaxBytes ?? 50 * 1024)
+        this.settings.toolResultMaxBytes = stepNumericPreset(
+          this.settings.toolResultMaxBytes ?? 50 * 1024,
+          [0, 10 * 1024, 50 * 1024, 100 * 1024, 500 * 1024],
+          direction
         );
-        this.settings.toolResultMaxBytes =
-          values[Math.max(0, Math.min(values.length - 1, index + direction))];
         break;
       }
       default: