@vanillagreen/pi-qol 1.7.4 → 1.8.0

package/README.md

@@ -1,7 +1,6 @@
 # pi-qol
 
 ![QOL extension settings panel](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/settings-panel.png)
-
 ![Session search popup](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/session-search.gif)
 ![/context usage breakdown](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/context-usage.png)
 
@@ -12,11 +11,7 @@ Quality-of-life extension for Pi: compact statusline, multiline input, session n
 - Compact statusline with repo, branch, model, thinking level, and context percent; can be disabled.
 - Newline-insert in the editor (multi-line drafts without auto-submit), with a fallback binding for terminals that can't distinguish the primary key.
 - Sessions auto-name from your first prompt. `/rename` overrides anytime.
-- `/search` browses previous sessions with snippet previews; the configured shortcut opens it instantly.
 - Session search reads prompt snippets line-by-line, so very large session JSONL files do not have to be materialized just to browse, search, or import context.
-- `/context` shows a Claude-style context-window breakdown.
-- `/handoff <goal>` drafts a focused prompt for a new session.
-- `/schedule 20m <message>` or `/schedule 1h45m <message>` sends a delayed prompt without invoking the model until the timer fires.
 - Optional rate-limit auto-resume sends a configurable continuation after reset.
 - Permission gate prompts before risky `bash` commands. Default match: `rm -Rf`.
 - Notifications for ready, questions, blocked states, and task completion.
@@ -26,6 +21,8 @@ Quality-of-life extension for Pi: compact statusline, multiline input, session n
 
 ## Install
 
+Requires Pi 0.80.4 or newer. Restart Pi after installation.
+
 Via [npm](https://www.npmjs.com/package/@vanillagreen/pi-qol):
 
 ```bash
@@ -39,8 +36,6 @@ cargo install --git https://github.com/vanillagreencom/vstack.git vstack
 vstack add vanillagreencom/vstack --pi-extension pi-qol --harness pi -y
 ```
 
-Restart Pi after installation.
-
 ## Commands
 
 | Command | Action |
@@ -48,166 +43,78 @@ Restart Pi after installation.
 | `/qol` | Open settings (or print status if extension-manager isn't installed). |
 | `/qol notify-test` | Send a test notification. |
 | `/rename [name]` | Set or show the current session's name. |
-| `/qol:rename` | Regenerate the session name from the first prompt. |
-| `/qol:rename:full` | Regenerate from the full conversation. |
-| `/context` | Show context-window usage with category breakdown. |
-| `/search [query]` | Open previous-session search. |
-| `/search:refresh` | Refresh the session search cache. |
-| `/handoff <goal>` | Draft a handoff prompt for a new session. |
+| `/qol:rename` / `/qol:rename:full` | Regenerate the session name from the first prompt, or from the full conversation. |
+| `/context` | Show a Claude-style context-window usage breakdown by category. |
+| `/search [query]` | Open previous-session search with snippet previews; the configured shortcut opens it instantly. |
+| `/search:refresh` | Refresh the session cache. |
+| `/handoff <goal>` | Draft a focused handoff prompt for a new session. |
 | `/schedule <delay> <message>` | Send a user message after a timer without invoking the model now. Example: `/schedule 1h45m retry the previous request`. |
 
-Arguments support autocomplete.
-
-`/schedule` accepts `ms`, `s`, `m`, `h`, and `d` units; bare numbers mean minutes. Compact composite durations are accepted in largest-to-smallest order, like `1h45m`, `45m10s`, or `1h45m30s`. Pending prompts render above the statusline like steering/follow-up previews until they are sent or cancelled. Manage pending prompts with `/schedule list` and `/schedule cancel <id|all>`. Schedules are stored in the Pi session and re-armed on reload/resume; if Pi is not running at the due time, an overdue prompt sends when that session is next loaded.
+Arguments support autocomplete. `/schedule` accepts `ms`, `s`, `m`, `h`, and `d` units; bare numbers mean minutes. Compact composite durations are accepted in largest-to-smallest order, like `1h45m`, `45m10s`, or `1h45m30s`. Pending prompts render above the statusline like steering/follow-up previews until they are sent or cancelled. Manage pending prompts with `/schedule list` and `/schedule cancel <id|all>`. Schedules are stored in the Pi session and re-armed on reload/resume; if Pi is not running at the due time, an overdue prompt sends when that session is next loaded.
 
 ## Settings
 
-Open `/extensions:settings`; settings appear under the **QOL** tab. Names below match the labels shown there.
-
-Project settings in `.pi/settings.json` apply only after Pi marks the workspace trusted; before trust, vstack Pi extensions read user/global settings only.
-
-Glyph style: each package exposes `glyphStyle` (`unicode` default, `ascii` for terminal-safe chrome). `@vanillagreen/pi-tool-renderer.globalGlyphStyleOverride=ascii` forces ASCII chrome across vstack Pi extensions while leaving tool/model/user content unchanged.
-
-### Statusline
-
-| Setting | What it does |
-| --- | --- |
-| Enable QOL editor helpers | Master toggle for QOL statusline, commands, notifications, search, compaction, and editor helpers. |
-| Show compact statusline | Render or disable the QOL statusline row. |
-| Replace built-in footer | Hide Pi's default footer while the QOL statusline is enabled. |
-| Use π prompt editor | Use the compact prompt editor. |
-| Show session name title | Show the session name above the prompt and in the tmux pane title; refreshes as soon as Pi reports a session metadata change. |
-| Sync session name to tmux window name | Rename the tmux window to `π <session>`. |
-| Input bottom padding | Blank lines below the prompt. |
-| Show dirty marker | Append `*` to the branch when the worktree is dirty. |
-
-### Input
-
-| Setting | What it does |
-| --- | --- |
-| shift+enter inserts newline | Insert a newline instead of submitting. |
-| Fallback newline key | Alternate binding for terminals that can't send the primary one. |
-| Style pending queue preview | Highlight Pi's pending-queue preview with a green left bar. |
-| Style image chips | Render `[Image #N]` placeholders as distinct chips. |
-| Show attachment count | Show a status badge when the draft has image placeholders. |
-
-### Session
-
-| Setting | What it does |
-| --- | --- |
-| Enable /rename command | Register the `/rename` command. |
-| Enable /schedule command | Register `/schedule` for timer-based prompts, useful for retrying after rate limits reset. |
-| Auto-resume after rate limits | Send the configured continuation after a detected reset; cancels on newer turn. |
-| Auto-name new sessions | Generate a friendly session name from the first prompt. |
-| Auto-rename model | Model used for title generation. |
-| Auto-rename fallback model | Model tried when the primary fails. |
-| Deterministic fallback | Title-case words, truncated prompt, or none if all model calls fail. |
-| Auto-rename prefix | Optional static prefix on every generated name. |
-| Notify on auto-rename | Show a notification when auto-renaming. |
-
-Advanced: input cap, title length, output tokens, timeout, custom prompt template, and debug logging.
-
-### Handoff
-
-| Setting | What it does |
-| --- | --- |
-| Enable /handoff command | Register the `/handoff` command. |
-| Review handoff prompt | Open an editor to edit the generated prompt before creating the session. |
-
-### Context window
-
-| Setting | What it does |
-| --- | --- |
-| Enable /context command | Register `/context`. |
-
-`/context` also estimates the serialized payload size of the messages that would be sent on the next request. When that payload crosses **Transcript-risk warn budget (chars)** a `Transcript risk` block appears below the compact buffer section even if token count is still under the context window — useful for catching large blob-shaped tool outputs that inflate the request long before token count alone would page anyone. If transcript-risk estimation itself errors, `/context` shows a sanitized error in the same block rather than silently hiding the warning.
-
-### Session search
-
-| Setting | What it does |
-| --- | --- |
-| Enable session search | Register `/search` and the overlay. |
-| Session search shortcut | Configurable; set to `none` to disable. |
-| Result limit | Max matching prompts returned. |
-| Visible session rows | Rows shown before scrolling; defaults to `8`. |
-| Preview snippets | Matching snippets shown on the preview screen. |
-| Session cache TTL | Seconds before the session list refreshes; `0` keeps it until you run `/search:refresh`. |
+Open `/extensions:settings`; settings appear under the **QOL** tab. Names below match the labels shown there, grouped as the editor groups them. Project settings in `.pi/settings.json` apply only after Pi marks the workspace trusted; before trust, vstack Pi extensions read user/global settings only. Glyph style: each package exposes `glyphStyle` (`unicode` default, `ascii` for terminal-safe chrome). `@vanillagreen/pi-tool-renderer.globalGlyphStyleOverride=ascii` forces ASCII chrome across vstack Pi extensions while leaving tool/model/user content unchanged.
 
-Summary settings (model, max tokens, input cap) tune the summarizer when you import context from a previous session.
+| Group | Setting | What it does |
+| --- | --- | --- |
+| Statusline | Enable QOL editor helpers | Master toggle for QOL statusline, commands, notifications, search, compaction, and editor helpers. |
+| Statusline | Show compact statusline | Render or disable the QOL statusline row. |
+| Statusline | Replace built-in footer | Hide Pi's default footer while the QOL statusline is enabled. |
+| Statusline | Use π prompt editor | Use the compact prompt editor. |
+| Statusline | Show session name title | Show the session name above the prompt and in the tmux pane title; refreshes as soon as Pi reports a session metadata change. |
+| Statusline | Sync session name to tmux window name | Rename the tmux window to `π <session>`. |
+| Statusline | Input bottom padding | Blank lines below the prompt. |
+| Statusline | Show dirty marker | Append `*` to the branch when the worktree is dirty. |
+| Input | shift+enter inserts newline | Insert a newline instead of submitting. |
+| Input | Fallback newline key | Alternate binding for terminals that can't send the primary one. |
+| Input | Style pending queue preview | Highlight Pi's pending-queue preview with a green left bar. |
+| Input | Style image chips | Render `[Image #N]` placeholders as distinct chips. |
+| Input | Show attachment count | Show a status badge when the draft has image placeholders. |
+| Session, Handoff, Context window, Session search | Enable /rename, /schedule, /handoff, /context, session search | One toggle each: register that command. Session search also registers its overlay; `/schedule` is useful for retrying after rate limits reset. |
+| Session | Auto-resume after rate limits | Send the configured continuation after a detected reset; cancels on newer turn. |
+| Session | Auto-name new sessions | Generate a friendly session name from the first prompt. |
+| Session | Auto-rename model / fallback model | Model used for title generation, and the model tried when the primary fails. |
+| Session | Deterministic fallback | Title-case words, truncated prompt, or none if all model calls fail. |
+| Session | Auto-rename prefix | Optional static prefix on every generated name. |
+| Session | Notify on auto-rename | Show a notification when auto-renaming. |
+| Handoff | Review handoff prompt | Open an editor to edit the generated prompt before creating the session. |
+| Session search | Session search shortcut | Configurable; set to `none` to disable. |
+| Session search | Result limit | Max matching prompts returned. |
+| Session search | Visible session rows | Rows shown before scrolling; defaults to `8`. |
+| Session search | Preview snippets | Matching snippets shown on the preview screen. |
+| Session search | Session cache TTL | Seconds before the session list refreshes; `0` keeps it until you run `/search:refresh`. |
+| Permission gate | Prompt before risky bash commands | Ask before bash commands matching the command list. Off by default; when enabled, non-interactive matches are blocked. |
+| Permission gate | Commands to prompt for | Comma-separated literal fragments or `/regex/flags`. |
+| Permission gate | Approval preview lines / characters | Cap the approval-prompt preview height and width. |
+| Compaction | Custom compaction summaries | Use QOL summaries instead of Pi's default, with Pi-standard transient provider retries when available. |
+| Compaction | Compaction model | Summarizer model. Defaults to `current`, meaning Pi's active model; set a provider/model when you want a dedicated larger-context summarizer. Thinking suffixes through `:max` are accepted, and Pi-resolved header/environment authentication is forwarded. |
+| Compaction | Compaction detail profile | `concise`, `balanced`, or `exhaustive`. |
+| Compaction | Include previous summary | Pass the previous summary for iterative continuity. |
+| Compaction | Fallback to Pi default compaction | Run Pi's default compaction if QOL's fails. |
+| Compaction | Show compaction notifications | Notify on compaction start/fail/complete. |
+| Compaction | Custom branch summaries | Use QOL's chunked summarizer for `/tree` branch summaries; branch summaries do not write handoff artifacts. |
+| Compaction | Remote compaction endpoint | Call a remote HTTP summarizer instead of a model. |
+| Compaction | Idle compaction trigger | Auto-compact after the session sits idle above a token threshold. Idle thresholds (token threshold, idle delay, fixed token limit, percent limit) tune when it fires. |
+| Long-session budget guard | Long-session budget guard | Master toggle for threshold-triggered bounded compaction. Default on. |
+| Long-session budget guard | Budget guard percent / token limit | Context-window percentage that fires the guard (default `85`; `-1` disables percent-based firing), and the absolute token count that fires it (default `-1`, meaning percent only). |
+| Long-session budget guard | Chunked compaction input cap | Max serialized characters per summarization request; long transcripts are chunked and summarized in bounded pieces so the compaction call itself cannot exceed provider buffer limits. `0` disables chunking. Default `240000`. |
+| Long-session budget guard | Write pre-compaction handoff artifact | Write a pre-compaction handoff artifact (previous summary, last task state, referenced files and artifacts) for budget-guard and enabled custom session compactions; branch summaries never write one. Write failures surface as a QOL warning notification. Default on. |
+| Long-session budget guard | Transcript-risk warn budget (chars) | `/context` warns when the serialized payload of messages-to-send exceeds this many characters, even if tokens are still below the context window. `0` disables. Default `600000`. |
+| Thinking | Hidden thinking label | Label shown when thinking blocks are hidden. |
+| Thinking | Show thinking timer | Show elapsed time next to collapsed `Thinking...` labels. |
+| Thinking | Working indicator mode | `animated` ticks every 80ms; switch to `static` if you see flashes when the chat overflows. |
+
+Advanced auto-rename settings (input cap, title length, output tokens, timeout, custom prompt template, debug logging) and session-search summary settings (model, max tokens, input cap — they tune the summarizer when you import context from a previous session) sit alongside the rows above.
+
+`/context` also estimates the serialized payload size of the messages that would be sent on the next request. When that payload crosses **Transcript-risk warn budget (chars)** a `Transcript risk` block appears below the compact buffer section even if token count is still under the context window — useful for catching large blob-shaped tool outputs that inflate the request long before token count alone would page anyone.
 
 ### Notifications
 
-Master toggle: **Enable notifications**.
-
-Triggers (notify when): ready, direction needed, question popups, all tasks complete, critical/blocked.
-
-Channels: terminal bell, **Mute bell sound**, native terminal notifications (OSC 777/99 or Windows toast), tmux `display-message`, tmux window marking, OSC passthrough, and an optional in-Pi UI notice.
-
-Tuning: cooldown seconds, title, ready message, body length, tmux durations.
-
-Notes:
-
-- **Terminal notification protocol** picks between OSC 99 (Kitty) and OSC 777 automatically.
-- **Bell when tmux window active** is off so you don't get bells while looking at Pi.
-- **Mute bell sound** keeps notification routing enabled but suppresses QOL-emitted BEL bytes and uses ST terminators for OSC 777/99 where supported. Terminals or operating systems may still play their own sound for native notifications outside QOL control.
-- **tmux native via client TTY** sends OSC notifications to attached tmux clients so notifications still appear when the Pi window is inactive.
-
-Use `/qol notify-test` to verify your terminal/tmux setup, including silent behavior with **Mute bell sound** enabled.
-
-### Permission gate
-
-| Setting | What it does |
-| --- | --- |
-| Prompt before risky bash commands | Ask before bash commands matching the command list. |
-| Commands to prompt for | Comma-separated literal fragments or `/regex/flags`. |
-| Approval preview lines | Cap the approval-prompt preview height. |
-| Approval preview characters | Cap the approval-prompt preview width. |
-
-Off by default. When enabled, non-interactive matches are blocked.
-
-### Compaction
-
-| Setting | What it does |
-| --- | --- |
-| Custom compaction summaries | Use QOL summaries instead of Pi's default, with Pi-standard transient provider retries when available. |
-| Compaction model | Summarizer model. Defaults to `current`, meaning Pi's active model; set a provider/model when you want a dedicated larger-context summarizer. Thinking suffixes through `:max` are accepted, and Pi-resolved header/environment authentication is forwarded. |
-| Compaction detail profile | `concise`, `balanced`, or `exhaustive`. |
-| Include previous summary | Pass the previous summary for iterative continuity. |
-| Fallback to Pi default compaction | Run Pi's default compaction if QOL's fails. |
-| Show compaction notifications | Notify on compaction start/fail/complete. |
-| Custom branch summaries | Use the QOL summarizer for `/tree` branch summaries. |
-| Remote compaction endpoint | Call a remote HTTP summarizer instead of a model. |
-| Idle compaction trigger | Auto-compact after the session sits idle above a token threshold. |
-
-Idle thresholds (token threshold, idle delay, fixed token limit, percent limit) tune when idle compaction fires.
+Master toggle: **Enable notifications**. Triggers (notify when): ready, direction needed, question popups, all tasks complete, critical/blocked. Channels: terminal bell, **Mute bell sound**, native terminal notifications (OSC 777/99 or Windows toast), tmux `display-message`, tmux window marking, OSC passthrough, and an optional in-Pi UI notice. Tuning: cooldown seconds, title, ready message, body length, tmux durations. **Terminal notification protocol** picks between OSC 99 (Kitty) and OSC 777 automatically. **Bell when tmux window active** is off so you don't get bells while looking at Pi. **Mute bell sound** keeps notification routing enabled but suppresses QOL-emitted BEL bytes and uses ST terminators for OSC 777/99 where supported; terminals or operating systems may still play their own sound for native notifications outside QOL control. **tmux native via client TTY** sends OSC notifications to attached tmux clients so notifications still appear when the Pi window is inactive. Use `/qol notify-test` to verify your terminal/tmux setup, including silent behavior with **Mute bell sound** enabled.
 
 ### Long-session budget guard
 
-For long autonomous runs the agent may not go idle, so idle compaction may never fire and the transcript can grow until provider/buffer limits hit. The budget guard runs on `agent_end` (not idle) and starts a compaction immediately when context usage crosses a percent of the model window or an absolute token limit. It fires once per threshold crossing — repeated `agent_end` events above the same threshold do not retrigger it, and the crossing key resets on a successful compaction or on a transient compaction failure (so the next `agent_end` retries).
-
-| Setting | What it does | Default |
-| --- | --- | --- |
-| Long-session budget guard | Master toggle for the agent_end budget guard. | on |
-| Budget guard percent | Context-window percentage that fires the guard. `-1` disables percent-based firing. | `85` |
-| Budget guard token limit | Absolute tokens that fire the guard. `-1` uses percent only. | `-1` |
-| Chunked compaction input cap | Max serialized characters per summarization request. Long transcripts are chunked, summarized chunk-by-chunk, then tree-reduced — every model/remote request (chunk + every reduce pass) is bounded so the compaction call itself cannot exceed provider buffer limits. `0` disables chunking. | `240000` |
-| Write pre-compaction handoff artifact | Before compaction, write `~/.pi/agent/vstack/sessions/<session>/pi-qol/handoff/<timestamp>.json` plus a `latest.json` pointer containing previous summary, last task state, and referenced files/artifacts. Write failures surface as a QOL warning notification and a `handoffArtifactError` field in the compaction details. | on |
-| Transcript-risk warn budget (chars) | `/context` shows a warning when the serialized payload of messages-to-send exceeds this many characters, even if tokens are still below the context window. `0` disables. | `600000` |
-
-When the budget guard fires it injects a sentinel into the compaction request so the QOL bounded handler always runs — chunked summarizer + handoff artifact — even if **Custom compaction summaries** is off. Manual compactions (`/tree`, idle compaction, user-triggered) still only use the QOL handler when **Custom compaction summaries** is on; otherwise they fall through to Pi's default compaction with no handoff artifact and no chunking. If you want every compaction to use the QOL bounded path, turn **Custom compaction summaries** on.
+For long autonomous runs the agent may not go idle, so the transcript can grow until provider or buffer limits hit. The budget guard starts bounded compaction when context usage crosses a configured threshold, while giving Pi's built-in compaction priority and avoiding duplicate attempts. While it runs, QOL keeps a persistent status line above the prompt (and in the normal status footer when the compact statusline is disabled); after Pi prints the compacted-summary block the line changes to `QOL budget guard finalizing compaction…` until finalization completes, so long reload gaps do not look frozen.
 
-While budget-guard compaction is running, QOL keeps a persistent status line above the prompt (and in the normal status footer when the compact statusline is disabled). After Pi prints the compacted-summary block, the line changes to `QOL budget guard finalizing compaction…` until `ctx.compact()` reports completion, so long reload/finalization gaps do not look frozen.
-
-Recommended values for long autonomous runs:
-
-- Keep **Long-session budget guard** on. Lower **Budget guard percent** to `75` if your provider buffers are tight.
-- Optionally turn **Custom compaction summaries** on so user-initiated and idle compactions also use the QOL chunked summarizer + handoff artifact. (Budget-guard-triggered compactions always use them regardless of this setting.)
-- Lower **Chunked compaction input cap** to ~`120000` when the summarizer model has a small context window.
-
-### Thinking
-
-| Setting | What it does |
-| --- | --- |
-| Hidden thinking label | Label shown when thinking blocks are hidden. |
-| Show thinking timer | Show elapsed time next to collapsed `Thinking...` labels. |
-| Working indicator mode | `animated` ticks every 80ms; switch to `static` if you see flashes when the chat overflows. |
+Budget-guard compaction always uses QOL's chunked summarizer, even if **Custom compaction summaries** is off, and writes a pre-compaction handoff artifact only when **Write pre-compaction handoff artifact** is enabled. Manual/user-triggered and idle compactions use the QOL chunked path only when **Custom compaction summaries** is on, and follow the same handoff-artifact toggle. `/tree` branch summaries separately use QOL's chunked summarizer when **Custom branch summaries** is on, but do not write handoff artifacts. When the relevant summarization setting is off, Pi uses its default behavior for that compaction type. Recommended for long autonomous runs: keep **Long-session budget guard** on, and lower **Budget guard percent** to `75` if your provider buffers are tight. Optionally turn **Custom compaction summaries** on so user-initiated and idle compactions also use the QOL chunked summarizer — with **Write pre-compaction handoff artifact** enabled, those compactions also write handoff artifacts. Lower **Chunked compaction input cap** to ~`120000` when the summarizer model has a small context window.

package/extensions/qol/budget-guard-runtime.ts

@@ -1,7 +1,6 @@
-// Runtime dispatch for the agent_end budget guard. Owns the last-crossing
-// key and in-flight flag so the guard fires exactly once per threshold
-// crossing, validates ctx.compact before marking in-flight, and clears the
-// crossing key on failure so the next agent_end can retry.
+// Runtime dispatch for the long-session budget guard. Agent-end observation and
+// settled-time dispatch are separate so Pi's built-in post-agent compaction gets
+// first refusal. The driver owns pending, satisfied, and in-flight trigger state.
 
 import { QOL_BUDGET_GUARD_SENTINEL, type BudgetTrigger } from "./budget-guard.js";
 
@@ -13,9 +12,9 @@ export interface GuardCompactOptions {
 	onError?: (error: Error) => void;
 }
 
-export interface GuardDispatchInput {
-	trigger: BudgetTrigger | undefined;
+export interface GuardPendingDispatchInput {
 	compact: ((options: GuardCompactOptions) => void) | undefined;
+	generation?: number;
 	notify: (message: string, level: GuardLevel) => void;
 	onStatus?: (message: string | undefined) => void;
 	staleCtx?: () => boolean;
@@ -24,82 +23,197 @@ export interface GuardDispatchInput {
 export type DispatchOutcome =
 	| { kind: "ignored" }
 	| { kind: "no-trigger" }
+	| { kind: "staged"; reason: string }
 	| { kind: "dedup" }
 	| { kind: "in-flight" }
 	| { kind: "no-compact-fn" }
 	| { kind: "dispatched"; reason: string }
-	| { kind: "dispatch-threw"; reason: string; error: string }
-	| { kind: "complete" }
-	| { kind: "failed"; error: string };
+	| { kind: "dispatch-threw"; reason: string; error: string };
+
+export interface GuardDispatchResult {
+	outcome: DispatchOutcome;
+	completion: Promise<void>;
+}
+
+interface InFlightDispatch {
+	generation: number;
+	key: string;
+	sessionCompactVersion: number;
+	resolveCompletion: () => void;
+}
+
+interface OwnedTrigger {
+	generation: number;
+	trigger: BudgetTrigger;
+}
+
+interface SatisfiedTrigger {
+	generation: number;
+	key: string;
+}
 
 export class BudgetGuardDriver {
-	private lastKey: string | undefined;
-	private inFlight = false;
+	private generation = 0;
+	private satisfiedTrigger: SatisfiedTrigger | undefined;
+	private pendingTrigger: OwnedTrigger | undefined;
+	private inFlight: InFlightDispatch | undefined;
+	private sessionCompactVersion = 0;
 
-	reset(): void {
-		this.lastKey = undefined;
-		this.inFlight = false;
+	reset(): number {
+		this.inFlight?.resolveCompletion();
+		this.generation += 1;
+		this.satisfiedTrigger = undefined;
+		this.pendingTrigger = undefined;
+		this.inFlight = undefined;
+		this.sessionCompactVersion = 0;
+		return this.generation;
 	}
 
-	/** Returns true if the next call to dispatch is allowed to fire. Visible for tests. */
+	/** Returns true when no compaction call is currently active. Visible for tests. */
 	get canFire(): boolean {
-		return !this.inFlight;
+		return this.inFlight === undefined;
 	}
 
 	get currentKey(): string | undefined {
-		return this.lastKey;
-	}
-
-	noteSessionCompacted(): void {
-		// Successful compaction drops usage below the budget; let the next
-		// crossing re-fire.
-		this.lastKey = undefined;
-		this.inFlight = false;
+		return this.inFlight?.key ?? this.pendingTrigger?.trigger.key ?? this.satisfiedTrigger?.key;
 	}
 
-	dispatch(input: GuardDispatchInput): DispatchOutcome {
-		if (input.staleCtx?.()) return { kind: "ignored" };
+	/**
+	 * Observe the trigger at agent_end without calling ctx.compact. Pi performs
+	 * its built-in post-agent compaction check before agent_settled, so staging
+	 * here prevents two compaction attempts from racing each other.
+	 */
+	stage(trigger: BudgetTrigger | undefined, staleCtx?: () => boolean, generation = this.generation): DispatchOutcome {
+		if (generation !== this.generation) return { kind: "ignored" };
+		if (staleCtx?.()) return { kind: "ignored" };
 		if (this.inFlight) return { kind: "in-flight" };
-		const trigger = input.trigger;
 		if (!trigger) {
-			this.lastKey = undefined;
+			this.pendingTrigger = undefined;
+			this.satisfiedTrigger = undefined;
 			return { kind: "no-trigger" };
 		}
-		if (trigger.key === this.lastKey) return { kind: "dedup" };
+		if (
+			(this.satisfiedTrigger?.generation === generation && trigger.key === this.satisfiedTrigger.key) ||
+			(this.pendingTrigger?.generation === generation && trigger.key === this.pendingTrigger.trigger.key)
+		) {
+			return { kind: "dedup" };
+		}
+		this.pendingTrigger = { generation, trigger };
+		return { kind: "staged", reason: trigger.reason };
+	}
+
+	/**
+	 * A completed Pi compaction satisfies whichever budget trigger is pending or
+	 * in flight. Keep that key suppressed until usage produces no trigger or a
+	 * genuinely different trigger key.
+	 */
+	noteSessionCompacted(generation = this.generation): boolean {
+		if (generation !== this.generation) return false;
+		this.sessionCompactVersion += 1;
+		const currentKey = this.inFlight?.key ?? this.pendingTrigger?.trigger.key;
+		if (currentKey) this.satisfiedTrigger = { generation, key: currentKey };
+		this.pendingTrigger = undefined;
+		return true;
+	}
+
+	/** Dispatch a trigger previously staged by agent_end. */
+	dispatchPending(input: GuardPendingDispatchInput): GuardDispatchResult {
+		const completed = (outcome: DispatchOutcome): GuardDispatchResult => ({ completion: Promise.resolve(), outcome });
+		const generation = input.generation ?? this.generation;
+		if (generation !== this.generation) return completed({ kind: "ignored" });
+		if (input.staleCtx?.()) return completed({ kind: "ignored" });
+		if (this.inFlight) return completed({ kind: "in-flight" });
+		const pending = this.pendingTrigger;
+		if (!pending || pending.generation !== generation) return completed({ kind: "no-trigger" });
+		const trigger = pending.trigger;
+		if (this.satisfiedTrigger?.generation === generation && trigger.key === this.satisfiedTrigger.key) {
+			this.pendingTrigger = undefined;
+			return completed({ kind: "dedup" });
+		}
 		if (typeof input.compact !== "function") {
 			input.notify(`QOL budget guard cannot fire: ctx.compact is unavailable (${trigger.reason}).`, "warning");
-			return { kind: "no-compact-fn" };
+			return completed({ kind: "no-compact-fn" });
 		}
+
 		input.notify(`QOL budget guard starting compaction: ${trigger.reason}`, "info");
 		input.onStatus?.(`QOL budget guard compacting session: ${trigger.reason}`);
-		this.inFlight = true;
-		this.lastKey = trigger.key;
+		let resolveCompletion = () => {};
+		const completion = new Promise<void>((resolve) => {
+			resolveCompletion = resolve;
+		});
+		const dispatch: InFlightDispatch = {
+			generation,
+			key: trigger.key,
+			resolveCompletion,
+			sessionCompactVersion: this.sessionCompactVersion,
+		};
+		this.pendingTrigger = undefined;
+		this.inFlight = dispatch;
+		this.satisfiedTrigger = { generation, key: trigger.key };
 		const instructions = `${QOL_BUDGET_GUARD_SENTINEL} QOL budget guard triggered at agent_end because ${trigger.reason}. Bound the summary input, preserve current task state, decisions, files, blockers, and next steps.`;
+
 		try {
 			input.compact({
 				customInstructions: instructions,
 				onComplete: () => {
-					this.inFlight = false;
-					input.onStatus?.(undefined);
-					input.notify("QOL budget guard compaction completed.", "info");
+					if (this.generation !== dispatch.generation || this.inFlight !== dispatch) return;
+					try {
+						this.inFlight = undefined;
+						this.satisfiedTrigger = { generation: dispatch.generation, key: dispatch.key };
+						input.onStatus?.(undefined);
+						input.notify("QOL budget guard compaction completed.", "info");
+					} finally {
+						dispatch.resolveCompletion();
+					}
 				},
 				onError: (error: Error) => {
-					this.inFlight = false;
-					// Allow the next agent_end to retry rather than poisoning the
-					// crossing key after a transient failure.
-					this.lastKey = undefined;
-					input.onStatus?.(undefined);
-					input.notify(`QOL budget guard compaction failed: ${error.message}`, "error");
+					if (this.generation !== dispatch.generation || this.inFlight !== dispatch) return;
+					const duplicateCompletedAfterDispatch =
+						error.message === "Already compacted" &&
+						this.sessionCompactVersion > dispatch.sessionCompactVersion;
+					if (duplicateCompletedAfterDispatch) {
+						try {
+							this.inFlight = undefined;
+							this.satisfiedTrigger = { generation: dispatch.generation, key: dispatch.key };
+							input.onStatus?.(undefined);
+						} finally {
+							dispatch.resolveCompletion();
+						}
+						return;
+					}
+
+					try {
+						this.inFlight = undefined;
+						// A later session_compact already satisfied this key even when
+						// this callback reports a different, visible error.
+						if (this.sessionCompactVersion === dispatch.sessionCompactVersion) {
+							this.satisfiedTrigger = undefined;
+						}
+						input.onStatus?.(undefined);
+						input.notify(`QOL budget guard compaction failed: ${error.message}`, "error");
+					} finally {
+						dispatch.resolveCompletion();
+					}
 				},
 			});
-			return { kind: "dispatched", reason: trigger.reason };
+			return { completion, outcome: { kind: "dispatched", reason: trigger.reason } };
 		} catch (error) {
-			this.inFlight = false;
-			this.lastKey = undefined;
-			input.onStatus?.(undefined);
+			if (this.generation === dispatch.generation && this.inFlight === dispatch) {
+				try {
+					this.inFlight = undefined;
+					this.satisfiedTrigger = undefined;
+					input.onStatus?.(undefined);
+					const message = error instanceof Error ? error.message : String(error);
+					input.notify(`QOL budget guard compaction failed to start: ${message}`, "error");
+					return { completion, outcome: { kind: "dispatch-threw", error: message, reason: trigger.reason } };
+				} finally {
+					dispatch.resolveCompletion();
+				}
+			}
+			dispatch.resolveCompletion();
 			const message = error instanceof Error ? error.message : String(error);
-			input.notify(`QOL budget guard compaction failed to start: ${message}`, "error");
-			return { kind: "dispatch-threw", error: message, reason: trigger.reason };
+			return { completion, outcome: { kind: "dispatch-threw", error: message, reason: trigger.reason } };
 		}
 	}
+
 }

package/extensions/qol/budget-guard.ts

@@ -106,9 +106,10 @@ export function evaluateTranscriptRisk(input: TranscriptRiskInput): TranscriptRi
 
 /**
  * Sentinel marker injected into customInstructions when budget guard triggers
- * a compaction. Detected by handleQolCompaction to force the bounded QOL path
- * + handoff artifact write regardless of the global compaction.customEnabled
- * setting.
+ * a compaction. Detected by handleQolCompaction to force bounded QOL
+ * summarization regardless of compaction.customEnabled. The same path invokes
+ * the handoff writer, whose artifact creation obeys the independent
+ * compaction.handoffArtifactEnabled toggle.
  */
 export const QOL_BUDGET_GUARD_SENTINEL = "[QOL_BUDGET_GUARD]";
 

package/extensions/qol/compaction.ts

@@ -256,9 +256,9 @@ export function writeBudgetHandoffArtifact(ctx: ExtensionContext, handoff: QolBu
 
 export async function handleQolCompaction(event: any, ctx: ExtensionContext): Promise<any> {
 	const isBudgetGuard = isBudgetGuardCompaction(event?.customInstructions);
-	// Budget-guard-triggered compactions force the QOL bounded path so the
-	// chunked summarizer + handoff artifact always run, even when the user
-	// has not flipped compaction.customEnabled on.
+	// Budget-guard-triggered compactions force the QOL bounded summarizer even
+	// when compaction.customEnabled is off. The handoff writer still honors its
+	// independent compaction.handoffArtifactEnabled toggle.
 	if (!isBudgetGuard && !settingBoolean("compaction.customEnabled", false, ctx.cwd)) return undefined;
 	const preparation = event.preparation ?? {};
 	const messages = [...(preparation.messagesToSummarize ?? []), ...(preparation.turnPrefixMessages ?? [])];
@@ -372,10 +372,10 @@ export type BudgetGuardTrigger = BudgetTrigger;
 export type TranscriptRiskState = TranscriptRiskResult;
 
 /**
- * Budget guard fires on agent_end (no idle wait) when context usage crosses a
- * percent of the model window or an absolute token limit. Returns a stable key
- * per crossing so the caller can suppress repeated triggers while usage stays
- * above the threshold.
+ * Budget guard evaluates on agent_end (no idle wait) when context usage crosses
+ * a percent of the model window or an absolute token limit. Returns a stable
+ * key per crossing so the caller can stage settled-time dispatch and suppress
+ * repeated triggers while usage stays above the threshold.
  */
 export function budgetGuardTrigger(ctx: ExtensionContext): BudgetGuardTrigger | undefined {
 	if (!settingBoolean("compaction.budgetGuardEnabled", true, ctx.cwd)) return undefined;

package/extensions/qol/constants.ts

@@ -39,9 +39,10 @@ export const DEFAULT_IDLE_COMPACTION_THRESHOLD_TOKENS = 200000;
 export const DEFAULT_IDLE_COMPACTION_SECONDS = 300;
 
 // Budget guard: catches long autonomous sessions before they hit provider/buffer
-// limits. Fires on agent_end (no idle wait) when usage crosses a percent or
-// absolute token threshold. One notification + one compaction trigger per
-// threshold crossing so it does not loop.
+// limits. Evaluates on agent_end (no idle wait) when usage crosses a percent
+// or absolute token threshold, then dispatches after Pi settles. One
+// notification + one compaction trigger per threshold crossing so it does not
+// race Pi's built-in post-agent compaction or loop.
 export const DEFAULT_BUDGET_GUARD_PERCENT = 85;
 export const DEFAULT_BUDGET_GUARD_TOKENS = -1;
 

package/extensions/qol/session-rename.ts

@@ -22,7 +22,7 @@ type AutoRenameFallbackMode = "none" | "truncate" | "words";
 interface AutoRenameAuth {
 	apiKey?: string;
 	env?: Record<string, string>;
-	headers?: Record<string, string>;
+	headers?: Record<string, string | null>;
 	label: string;
 	model: any;
 	source: string;
@@ -237,10 +237,13 @@ function autoRenameModelSettings(cwd?: string): string[] {
 		.filter((value, index, all) => all.findIndex((candidate) => candidate.toLowerCase() === value.toLowerCase()) === index);
 }
 
-function headerRecord(headers: unknown): Record<string, string> | undefined {
+// Pi resolves provider headers as `ProviderHeaders` (`Record<string, string | null>`).
+// A `null` value is a header-deletion marker that pi-ai acts on, so it must survive to
+// the stream unchanged — dropping it silently re-sends the header we were told to remove.
+export function headerRecord(headers: unknown): Record<string, string | null> | undefined {
 	if (!headers || typeof headers !== "object" || Array.isArray(headers)) return undefined;
 	const entries = Object.entries(headers as Record<string, unknown>)
-		.filter((entry): entry is [string, string] => typeof entry[1] === "string" && entry[1].length > 0);
+		.filter((entry): entry is [string, string | null] => entry[1] === null || (typeof entry[1] === "string" && entry[1].length > 0));
 	return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }
 

package/extensions/qol.ts

@@ -264,6 +264,7 @@ export default function qol(pi: ExtensionAPI): void {
 
 	const budgetGuardDriver = new BudgetGuardDriver();
 	let budgetGuardStatus: string | undefined;
+	let budgetGuardSession: { generation: number; sessionManager: unknown } | undefined;
 
 	const setBudgetGuardStatus = (ctx: ExtensionContext, message: string | undefined) => {
 		budgetGuardStatus = message;
@@ -273,12 +274,32 @@ export default function qol(pi: ExtensionAPI): void {
 		}
 	};
 
-	const resetBudgetGuard = () => {
+	const budgetGuardGenerationForContext = (ctx: ExtensionContext): number | undefined => {
+		if (!budgetGuardSession) return undefined;
+		try {
+			return ctx.sessionManager === budgetGuardSession.sessionManager ? budgetGuardSession.generation : undefined;
+		} catch (error) {
+			if (isStaleCtxError(error)) return undefined;
+			throw error;
+		}
+	};
+
+	const startBudgetGuardSession = (ctx: ExtensionContext) => {
+		const generation = budgetGuardDriver.reset();
+		budgetGuardSession = { generation, sessionManager: ctx.sessionManager };
+		budgetGuardStatus = undefined;
+	};
+
+	const resetBudgetGuard = (ctx: ExtensionContext) => {
+		if (budgetGuardGenerationForContext(ctx) === undefined) return;
 		budgetGuardDriver.reset();
+		budgetGuardSession = undefined;
 		budgetGuardStatus = undefined;
 	};
 
-	const maybeFireBudgetGuard = (ctx: ExtensionContext) => {
+	const stageBudgetGuard = (ctx: ExtensionContext) => {
+		const generation = budgetGuardGenerationForContext(ctx);
+		if (generation === undefined) return;
 		let trigger;
 		try {
 			trigger = budgetGuardTrigger(ctx);
@@ -286,6 +307,12 @@ export default function qol(pi: ExtensionAPI): void {
 			if (isStaleCtxError(error)) return;
 			throw error;
 		}
+		budgetGuardDriver.stage(trigger, undefined, generation);
+	};
+
+	const fireStagedBudgetGuard = async (ctx: ExtensionContext) => {
+		const generation = budgetGuardGenerationForContext(ctx);
+		if (generation === undefined) return;
 		const notifySafely = (message: string, level: "info" | "warning" | "error") => {
 			try {
 				if (ctx.hasUI && settingBoolean("compaction.notify", true, ctx.cwd)) ctx.ui.notify(message, level);
@@ -294,12 +321,15 @@ export default function qol(pi: ExtensionAPI): void {
 				throw error;
 			}
 		};
-		budgetGuardDriver.dispatch({
+		const dispatch = budgetGuardDriver.dispatchPending({
 			compact: typeof ctx.compact === "function" ? ctx.compact.bind(ctx) : undefined,
+			generation,
 			notify: notifySafely,
 			onStatus: (message) => setBudgetGuardStatus(ctx, message),
-			trigger,
 		});
+		// Supported Pi hosts always route ctx.compact terminal success/failure to
+		// one callback. Await it so Pi cannot emit terminal settlement first.
+		await dispatch.completion;
 	};
 
 	const scheduleIdleCompaction = (ctx: ExtensionContext) => {
@@ -565,7 +595,7 @@ export default function qol(pi: ExtensionAPI): void {
 		subscribeCavemanBridge();
 		latestSystemPromptOptions = undefined;
 		resetAutoRename();
-		resetBudgetGuard();
+		startBudgetGuardSession(ctx);
 		resetThinkingTimer(ctx);
 		const scheduleEnabled = settingBoolean("enableScheduleCommand", true, ctx.cwd);
 		const rateLimitAutoResumeEnabled = rateLimitAutoResumeController.enabled(ctx);
@@ -639,7 +669,7 @@ export default function qol(pi: ExtensionAPI): void {
 		scheduleController.clearTimers();
 		rateLimitAutoResumeController.clearTimers();
 		resetAutoRename();
-		resetBudgetGuard();
+		resetBudgetGuard(ctx);
 		clearIdleCompactionTimer();
 		clearQuestionSubscribeTimer();
 		if (sessionSearchWarmupTimer) clearTimeout(sessionSearchWarmupTimer);
@@ -649,7 +679,6 @@ export default function qol(pi: ExtensionAPI): void {
 		questionUnsubscribe?.();
 		questionUnsubscribe = undefined;
 		currentCtx = undefined;
-		budgetGuardStatus = undefined;
 		const host = globalThis as unknown as Record<PropertyKey, unknown>;
 		if (host[QOL_NOTIFICATION_SERVICE_SYMBOL] === notificationService) delete host[QOL_NOTIFICATION_SERVICE_SYMBOL];
 		ctx.ui.setStatus(STATUS_KEY, undefined);
@@ -720,7 +749,7 @@ export default function qol(pi: ExtensionAPI): void {
 			requestRender();
 		}
 		rateLimitAutoResumeController.noteAgentEnd(event, ctx);
-		maybeFireBudgetGuard(ctx);
+		stageBudgetGuard(ctx);
 		scheduleIdleCompaction(ctx);
 		void attemptAutoRename(ctx);
 		const text = lastAssistantTextFromAgentEnd(event, ctx);
@@ -743,11 +772,16 @@ export default function qol(pi: ExtensionAPI): void {
 		}
 		sendQolNotification(ctx, "ready", settingString("notification.readyMessage", "Ready for input", ctx.cwd), "info", "ready");
 	});
+	pi.on("agent_settled", async (_event, ctx) => {
+		await fireStagedBudgetGuard(ctx);
+	});
 	pi.on("session_compact", (_event, ctx) => {
+		const generation = budgetGuardGenerationForContext(ctx);
+		if (generation === undefined) return;
 		if (budgetGuardStatus) setBudgetGuardStatus(ctx, "QOL budget guard finalizing compaction…");
-		// After a successful compaction usage drops below the budget, so reset the
-		// crossing key so the next threshold crossing re-fires the guard.
-		budgetGuardDriver.noteSessionCompacted();
+		// Pi core can compact after agent_end but before agent_settled. Mark the
+		// staged or in-flight trigger satisfied so the same crossing cannot refire.
+		budgetGuardDriver.noteSessionCompacted(generation);
 		if (!ctx.hasUI) return;
 		void refreshStatusline(ctx);
 		requestRender();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillagreen/pi-qol",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "Pi quality-of-life extension: compact statusline/π prompt, reliable multiline input, styled pasted-image chips, session naming/search/context import, scheduled prompts, handoff, permission prompts, notifications, custom compaction, and a collapsed-thinking timer.",
   "license": "MIT",
   "keywords": [
@@ -875,7 +875,7 @@
         {
           "key": "compaction.budgetGuardEnabled",
           "label": "Long-session budget guard",
-          "description": "Trigger compaction on agent_end (no idle wait) when context usage crosses budgetPercent or budgetTokens. Designed for long autonomous runs so transcript growth cannot silently hit provider/buffer limits. Fires once per threshold crossing, not in a loop.",
+          "description": "Start bounded compaction when an active session crosses the configured context budget, while giving Pi's built-in compaction priority. Designed for long autonomous runs so transcript growth cannot silently hit provider or buffer limits. Fires once per threshold crossing, not in a loop.",
           "type": "boolean",
           "default": true,
           "category": "Compaction Budget Guard",
@@ -884,7 +884,7 @@
         {
           "key": "compaction.budgetPercent",
           "label": "Budget guard percent",
-          "description": "Context-window percentage that fires the budget guard at agent_end. Set -1 to disable percent-based firing and rely on absolute tokens instead.",
+          "description": "Context-window percentage that triggers the budget guard. Set -1 to disable percent-based triggering and rely on the absolute token limit instead.",
           "type": "number",
           "default": 85,
           "category": "Compaction Budget Guard",
@@ -893,7 +893,7 @@
         {
           "key": "compaction.budgetTokens",
           "label": "Budget guard token limit",
-          "description": "Absolute token count above which the budget guard fires at agent_end. Set -1 to use only budgetPercent.",
+          "description": "Absolute token count that triggers the budget guard. Set -1 to use only the percentage threshold.",
           "type": "number",
           "default": -1,
           "category": "Compaction Budget Guard",
@@ -911,7 +911,7 @@
         {
           "key": "compaction.handoffArtifactEnabled",
           "label": "Write pre-compaction handoff artifact",
-          "description": "Before compaction, write a JSON handoff artifact under ~/.pi/agent/vstack/sessions/<session>/pi-qol/handoff/ containing the previous summary, last task state, and recently-referenced file/artifact paths. Always writes a stamped file and a latest.json pointer. Runs whenever the QOL bounded compaction handler runs — that is, on every budget-guard-triggered compaction (regardless of compaction.customEnabled), and on manual/idle compactions only when compaction.customEnabled is on. Write failures surface a QOL warning and a handoffArtifactError field in the compaction details.",
+          "description": "When enabled, write a JSON handoff artifact under ~/.pi/agent/vstack/sessions/<session>/pi-qol/handoff/ containing the previous summary, last task state, and recently-referenced file/artifact paths. Each write creates a stamped file and a latest.json pointer. Applies to every budget-guard compaction (regardless of compaction.customEnabled), and to manual/idle compactions only when compaction.customEnabled is on. Write failures surface a QOL warning and a handoffArtifactError field in the compaction details.",
           "type": "boolean",
           "default": true,
           "category": "Compaction Budget Guard",
@@ -965,7 +965,7 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.80.4",
     "@earendil-works/pi-tui": "*"
   },
   "files": [