@pi-unipi/unipi 2.0.2 → 2.0.4

package/packages/compactor/src/index.ts

@@ -3,9 +3,16 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { MODULES, UNIPI_EVENTS, COMPACTOR_COMMANDS, COMPACTOR_TOOLS, emitEvent } from "@pi-unipi/core";
+import { MODULES, UNIPI_EVENTS, COMPACTOR_COMMANDS, COMPACTOR_TOOLS, COMPACTOR_INSTRUCTION, emitEvent } from "@pi-unipi/core";
 import { scaffoldConfig, loadConfig } from "./config/manager.js";
 import { registerCompactionHooks } from "./compaction/hooks.js";
+import {
+  createAutoCompactionState,
+  decideAutoCompaction,
+  markAutoCompactionComplete,
+  markAutoCompactionError,
+  type AutoCompactionState,
+} from "./compaction/auto-trigger.js";
 import { SessionDB, getWorktreeSuffix } from "./session/db.js";
 import { extractEventsFromToolResult } from "./session/extract.js";
 import { injectResumeSnapshot } from "./session/resume-inject.js";
@@ -26,6 +33,12 @@ function createDebugLogger(getConfig: () => { debug: boolean }) {
   };
 }
 
+const formatTokenCount = (n: number): string => {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+};
+
 /** Measure byte size of a tool_result event's response content. */
 function measureResponseBytes(event: any): number {
   try {
@@ -59,6 +72,7 @@ export default function compactorExtension(pi: ExtensionAPI): void {
   let sessionDB: SessionDB | null = null;
   let executor: PolyglotExecutor | null = null;
   let config = loadConfig();
+  let autoCompactionState: AutoCompactionState = createAutoCompactionState();
   let cachedBlocks: NormalizedBlock[] = [];
   let currentSessionId = "default";
   const counters: RuntimeCounters = {
@@ -148,6 +162,7 @@ export default function compactorExtension(pi: ExtensionAPI): void {
     runtimeStats.sessionStart = Date.now();
     runtimeStats.cacheHits = 0;
     runtimeStats.cacheBytesSaved = 0;
+    autoCompactionState = createAutoCompactionState();
 
     sessionDB?.ensureSession(fullSessionId, projectDir);
 
@@ -284,6 +299,64 @@ export default function compactorExtension(pi: ExtensionAPI): void {
     }
   });
 
+  pi.on("turn_end", async (_event, ctx) => {
+    const cwd = (ctx as any).cwd ?? process.cwd();
+    config = loadConfig(cwd);
+
+    const decision = decideAutoCompaction({
+      config: config.autoCompaction,
+      usage: ctx.getContextUsage?.(),
+      state: autoCompactionState,
+      nowMs: Date.now(),
+    });
+    autoCompactionState = decision.state;
+
+    debug("auto_compaction_decision", {
+      enabled: config.autoCompaction.enabled,
+      reason: decision.reason,
+      shouldTrigger: decision.shouldTrigger,
+      percent: decision.usage?.percent,
+      tokens: decision.usage?.tokens,
+      thresholdPercent: decision.thresholdPercent,
+      cooldownRemainingMs: decision.cooldownRemainingMs,
+      tokenGrowth: decision.tokenGrowth,
+    });
+
+    if (!decision.shouldTrigger) return;
+
+    const notify = config.autoCompaction.notify;
+    if (notify && decision.usage) {
+      ctx.ui.notify(
+        `Auto-compacting at ${decision.usage.percent.toFixed(1)}% context (~${formatTokenCount(decision.usage.tokens)} tokens; threshold ${decision.thresholdPercent}%).`,
+        "info",
+      );
+    }
+
+    try {
+      ctx.compact({
+        customInstructions: COMPACTOR_INSTRUCTION,
+        onComplete: () => {
+          autoCompactionState = markAutoCompactionComplete(autoCompactionState);
+          if (notify) {
+            ctx.ui.notify("Auto-compaction completed.", "info");
+          }
+        },
+        onError: (err: Error) => {
+          autoCompactionState = markAutoCompactionError(autoCompactionState, Date.now());
+          const benign = err.message === "Compaction cancelled" || err.message === "Already compacted";
+          if (notify && !benign) {
+            ctx.ui.notify(`Auto-compaction failed: ${err.message}`, "warning");
+          }
+        },
+      });
+    } catch (err) {
+      autoCompactionState = markAutoCompactionError(autoCompactionState, Date.now());
+      if (notify) {
+        ctx.ui.notify(`Auto-compaction failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+      }
+    }
+  });
+
   pi.on("session_before_compact", async (event, _ctx) => {
     if (sessionDB) {
       // Use closure currentSessionId — Pi's session_before_compact event

package/packages/compactor/src/tools/context-budget.ts

@@ -2,6 +2,8 @@
  * context_budget tool — estimate remaining context window
  */
 
+import type { AutoCompactionConfig } from "../types.js";
+
 export interface ContextBudgetResult {
   percentFull: number;
   remainingTokens: number;
@@ -13,6 +15,7 @@ export interface ContextBudgetResult {
 export function estimateContextBudget(
   tokensBefore?: number,
   contextWindowSize?: number,
+  autoCompaction?: Pick<AutoCompactionConfig, "enabled" | "thresholdPercent">,
 ): ContextBudgetResult | null {
   const windowSize = contextWindowSize ?? 200000; // Default 200K context
   const used = tokensBefore ?? 0;
@@ -33,6 +36,15 @@ export function estimateContextBudget(
     advice = "Context has plenty of room. No compaction needed yet.";
   }
 
+  if (autoCompaction?.enabled) {
+    const threshold = autoCompaction.thresholdPercent;
+    if (percentFull >= threshold) {
+      advice += ` UniPi percentage auto-compaction is enabled at ${threshold}% and usage is above that threshold, subject to cooldown/repeat safeguards.`;
+    } else {
+      advice += ` UniPi percentage auto-compaction is enabled at ${threshold}%.`;
+    }
+  }
+
   const message = `Context: ~${percentFull}% full (estimated ${remaining.toLocaleString()} tokens remaining)`;
 
   return { percentFull, remainingTokens: remaining, totalTokens: windowSize, message, advice };
@@ -42,8 +54,12 @@ export function estimateContextBudget(
  * The context_budget tool handler.
  * Called from the tool registration — receives tokensBefore from Pi context.
  */
-export function contextBudgetTool(tokensBefore?: number): string {
-  const budget = estimateContextBudget(tokensBefore);
+export function contextBudgetTool(
+  tokensBefore?: number,
+  contextWindowSize?: number,
+  autoCompaction?: Pick<AutoCompactionConfig, "enabled" | "thresholdPercent">,
+): string {
+  const budget = estimateContextBudget(tokensBefore, contextWindowSize, autoCompaction);
   if (!budget) return "Context budget: Unknown (no token data available from session).";
 
   return `${budget.message}\nAdvice: ${budget.advice}`;

package/packages/compactor/src/tools/register.ts

@@ -291,17 +291,25 @@ export function registerCompactorTools(pi: ExtensionAPI, deps: CompactorToolDeps
     label: "Context Budget",
     description: "Estimate remaining context window (% full, tokens left) and get advice on whether to compact.",
     parameters: Type.Object({}),
-    async execute(): Promise<import("@mariozechner/pi-coding-agent").AgentToolResult<unknown>> {
-      const blocks = deps.getBlocks();
-      const estimatedTokens = blocks.reduce((sum, b) => {
-        const text = b.kind === "tool_call"
-          ? `${b.name} ${JSON.stringify((b as any).args ?? {})}`
-          : b.kind === "tool_result"
-            ? `${b.name} ${(b as any).text ?? ""}`
-            : (b as any).text ?? "";
-        return sum + Math.ceil(text.length / 4);
-      }, 0);
-      const message = contextBudgetTool(estimatedTokens);
+    async execute(_toolCallId: string, _params: any, _signal?: AbortSignal, _onUpdate?: unknown, ctx?: ExtensionContext): Promise<import("@mariozechner/pi-coding-agent").AgentToolResult<unknown>> {
+      const config = loadConfig(ctx?.cwd ?? process.cwd());
+      const liveUsage = ctx?.getContextUsage?.();
+      let estimatedTokens: number | undefined = liveUsage?.tokens ?? undefined;
+      let contextWindow = liveUsage?.contextWindow;
+
+      if (estimatedTokens === undefined) {
+        const blocks = deps.getBlocks();
+        estimatedTokens = blocks.reduce((sum, b) => {
+          const text = b.kind === "tool_call"
+            ? `${b.name} ${JSON.stringify((b as any).args ?? {})}`
+            : b.kind === "tool_result"
+              ? `${b.name} ${(b as any).text ?? ""}`
+              : (b as any).text ?? "";
+          return sum + Math.ceil(text.length / 4);
+        }, 0);
+      }
+
+      const message = contextBudgetTool(estimatedTokens, contextWindow, config.autoCompaction);
       return textResult(message);
     },
   } as any));

package/packages/compactor/src/tui/settings-overlay.ts

@@ -18,8 +18,8 @@ import { existsSync, unlinkSync } from "node:fs";
 
 // ─── Section types ─────────────────────────────────────────────────────
 
-type Section = "presets" | "strategies" | "pipeline";
-const SECTIONS: Section[] = ["presets", "strategies", "pipeline"];
+type Section = "presets" | "strategies" | "auto" | "pipeline";
+const SECTIONS: Section[] = ["presets", "strategies", "auto", "pipeline"];
 
 // ─── Strategy item definition ──────────────────────────────────────────
 
@@ -160,6 +160,10 @@ const PIPELINE_ITEMS: PipelineDef[] = [
 
 const PRESETS: CompactorPreset[] = ["precise", "balanced", "thorough", "lean"];
 
+const THRESHOLD_VALUES = ["60%", "70%", "75%", "80%", "85%", "90%", "95%"];
+const COOLDOWN_VALUES = ["0s", "30s", "60s", "5m", "10m"];
+const REPEAT_GROWTH_VALUES = ["0", "1k", "4k", "8k", "16k", "32k"];
+
 const PRESET_DESCRIPTIONS: Record<string, { summary: string; detail: string }> = {
   precise: {
     summary: "Code-heavy, minimal waste — compaction: full, sandbox: safe-only",
@@ -207,6 +211,40 @@ function borderLine(innerWidth: number, edge: "top" | "bottom"): string {
   return `\x1b[90m${left}${"─".repeat(innerWidth)}${right}\x1b[0m`;
 }
 
+function uniqueValues(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function formatPercent(value: number): string {
+  return `${Math.round(value)}%`;
+}
+
+function parsePercent(value: string): number {
+  return Number(value.replace("%", ""));
+}
+
+function formatCooldown(ms: number): string {
+  if (ms === 0) return "0s";
+  if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+  return `${Math.round(ms / 1000)}s`;
+}
+
+function parseCooldown(value: string): number {
+  if (value.endsWith("m")) return Number(value.slice(0, -1)) * 60_000;
+  if (value.endsWith("s")) return Number(value.slice(0, -1)) * 1000;
+  return Number(value);
+}
+
+function formatGrowthTokens(tokens: number): string {
+  if (tokens >= 1000 && tokens % 1000 === 0) return `${tokens / 1000}k`;
+  return String(tokens);
+}
+
+function parseGrowthTokens(value: string): number {
+  if (value.endsWith("k")) return Number(value.slice(0, -1)) * 1000;
+  return Number(value);
+}
+
 // ─── Main component ────────────────────────────────────────────────────
 
 /**
@@ -224,6 +262,7 @@ export class CompactorSettingsOverlay implements Component {
   // Per-section SettingsList instances
   private presetList!: SettingsList;
   private strategyList!: SettingsList;
+  private autoList!: SettingsList;
   private pipelineList!: SettingsList;
 
   constructor(opts?: { cwd?: string }) {
@@ -290,6 +329,53 @@ export class CompactorSettingsOverlay implements Component {
       { enableSearch: true },
     );
 
+    // ── Auto-compaction trigger list ──────────────────────────────────
+    const autoItems: SettingItem[] = [
+      {
+        id: "auto:enabled",
+        label: "Percentage Trigger",
+        description: "UniPi-managed auto-compaction based on context percentage",
+        currentValue: this.config.autoCompaction.enabled ? "on" : "off",
+        values: ["on", "off"],
+      },
+      {
+        id: "auto:thresholdPercent",
+        label: "Threshold",
+        description: "Trigger when Pi reports context usage at or above this percent",
+        currentValue: formatPercent(this.config.autoCompaction.thresholdPercent),
+        values: uniqueValues([...THRESHOLD_VALUES, formatPercent(this.config.autoCompaction.thresholdPercent)]),
+      },
+      {
+        id: "auto:cooldownMs",
+        label: "Cooldown",
+        description: "Minimum delay between UniPi-triggered compaction attempts",
+        currentValue: formatCooldown(this.config.autoCompaction.cooldownMs),
+        values: uniqueValues([...COOLDOWN_VALUES, formatCooldown(this.config.autoCompaction.cooldownMs)]),
+      },
+      {
+        id: "auto:repeatMinGrowthTokens",
+        label: "Repeat Growth",
+        description: "If still above threshold after compaction, require this many new tokens",
+        currentValue: formatGrowthTokens(this.config.autoCompaction.repeatMinGrowthTokens),
+        values: uniqueValues([...REPEAT_GROWTH_VALUES, formatGrowthTokens(this.config.autoCompaction.repeatMinGrowthTokens)]),
+      },
+      {
+        id: "auto:notify",
+        label: "Notifications",
+        description: "Notify when UniPi auto-compaction triggers or fails",
+        currentValue: this.config.autoCompaction.notify ? "on" : "off",
+        values: ["on", "off"],
+      },
+    ];
+
+    this.autoList = new SettingsList(
+      autoItems,
+      8,
+      THEME,
+      (id, newValue) => this.onAutoChange(id, newValue),
+      () => this.onCancel(),
+    );
+
     // ── Pipeline list ─────────────────────────────────────────────────
     const pipelineItems: SettingItem[] = PIPELINE_ITEMS.map((p) => ({
       id: `pipeline:${p.key}`,
@@ -312,6 +398,7 @@ export class CompactorSettingsOverlay implements Component {
 
   private get currentList(): SettingsList {
     if (this.section === "strategies") return this.strategyList;
+    if (this.section === "auto") return this.autoList;
     if (this.section === "pipeline") return this.pipelineList;
     return this.presetList;
   }
@@ -332,8 +419,9 @@ export class CompactorSettingsOverlay implements Component {
     const presetName = id.replace("preset:", "") as CompactorPreset;
     if (PRESETS.includes(presetName)) {
       this.config = applyPreset(presetName);
-      // Update all strategy/pipeline items to reflect new config
+      // Update all strategy/auto/pipeline items to reflect new config
       this.refreshStrategyValues();
+      this.refreshAutoValues();
       this.refreshPipelineValues();
       // Update preset indicators
       for (const name of PRESETS) {
@@ -366,6 +454,39 @@ export class CompactorSettingsOverlay implements Component {
     }
   }
 
+  private onAutoChange(id: string, newValue: string): void {
+    const key = id.replace("auto:", "");
+    switch (key) {
+      case "enabled":
+        this.config.autoCompaction.enabled = newValue === "on";
+        break;
+      case "thresholdPercent":
+        this.config.autoCompaction.thresholdPercent = parsePercent(newValue);
+        break;
+      case "cooldownMs":
+        this.config.autoCompaction.cooldownMs = parseCooldown(newValue);
+        break;
+      case "repeatMinGrowthTokens":
+        this.config.autoCompaction.repeatMinGrowthTokens = parseGrowthTokens(newValue);
+        break;
+      case "notify":
+        this.config.autoCompaction.notify = newValue === "on";
+        break;
+      default:
+        return;
+    }
+
+    this.autoList.updateValue(id, this.formatAutoValue(key));
+
+    // Update preset indicators
+    for (const name of PRESETS) {
+      this.presetList.updateValue(
+        `preset:${name}`,
+        detectPreset(this.config) === name ? "✓ active" : "",
+      );
+    }
+  }
+
   private onPipelineChange(id: string, newValue: string): void {
     const key = id.replace("pipeline:", "");
     const item = PIPELINE_ITEMS.find((p) => p.key === key);
@@ -395,12 +516,30 @@ export class CompactorSettingsOverlay implements Component {
     return mode;
   }
 
+  private formatAutoValue(key: string): string {
+    const auto = this.config.autoCompaction;
+    switch (key) {
+      case "enabled": return auto.enabled ? "on" : "off";
+      case "thresholdPercent": return formatPercent(auto.thresholdPercent);
+      case "cooldownMs": return formatCooldown(auto.cooldownMs);
+      case "repeatMinGrowthTokens": return formatGrowthTokens(auto.repeatMinGrowthTokens);
+      case "notify": return auto.notify ? "on" : "off";
+      default: return "";
+    }
+  }
+
   private refreshStrategyValues(): void {
     for (const s of STRATEGIES) {
       this.strategyList.updateValue(`strategy:${s.key}`, this.formatStrategyValue(s));
     }
   }
 
+  private refreshAutoValues(): void {
+    for (const key of ["enabled", "thresholdPercent", "cooldownMs", "repeatMinGrowthTokens", "notify"]) {
+      this.autoList.updateValue(`auto:${key}`, this.formatAutoValue(key));
+    }
+  }
+
   private refreshPipelineValues(): void {
     for (const p of PIPELINE_ITEMS) {
       this.pipelineList.updateValue(`pipeline:${p.key}`, p.getValue(this.config) ? "on" : "off");

package/packages/compactor/src/types.ts

@@ -88,6 +88,20 @@ export interface CompactorStrategyConfig {
   autoDetect?: "git" | null;
 }
 
+/** UniPi-managed percentage auto-compaction trigger settings. */
+export interface AutoCompactionConfig {
+  /** Enable the extension-managed percentage trigger. Disabled by default for backward compatibility. */
+  enabled: boolean;
+  /** Trigger when Pi reports context usage at or above this percent (0-100 scale). */
+  thresholdPercent: number;
+  /** Minimum delay between UniPi-triggered compaction attempts. */
+  cooldownMs: number;
+  /** When usage stays above threshold after compaction, require this many new tokens before repeating. */
+  repeatMinGrowthTokens: number;
+  /** Show user notifications for UniPi-triggered compaction attempts/results. */
+  notify: boolean;
+}
+
 export interface CompactorConfig {
   // Compaction strategies
   sessionGoals: CompactorStrategyConfig & { mode: "full" | "brief" | "off" };
@@ -112,6 +126,9 @@ export interface CompactorConfig {
     customNoisePatterns: string[];
   };
 
+  // Auto compaction trigger
+  autoCompaction: AutoCompactionConfig;
+
   // Global settings
   overrideDefaultCompaction: boolean;
   debug: boolean;

package/packages/core/events.ts

@@ -409,6 +409,8 @@ export interface UnipiNotificationSentEvent {
   platforms: string[];
   /** Whether all platforms succeeded */
   success: boolean;
+  /** Platforms where notification was suppressed (e.g. window focused) */
+  suppressedPlatforms?: string[];
   /** ISO timestamp */
   timestamp: string;
 }

package/packages/notify/README.md

@@ -2,7 +2,7 @@
 
 Push notifications when things happen. Workflow finishes, Ralph loop completes, MCP server errors — notify sends alerts to native OS, Gotify, Telegram, or ntfy.
 
-Configure once, get alerts everywhere. Per-event platform routing lets you send critical errors to Telegram and routine completions to Gotify.
+Configure once, get alerts everywhere. Per-event platform routing lets you send critical errors to Telegram and routine completions to Gotify. Native desktop notifications can also be suppressed while the Pi window is focused.
 
 ## Commands
 
@@ -53,7 +53,7 @@ Desktop notifications via [node-notifier](https://github.com/mikaelbr/node-notif
 - **macOS:** terminal-notifier
 - **Linux:** notify-send / libnotify
 
-Zero configuration — works out of the box.
+Zero configuration — works out of the box. Set `native.suppressWhenFocused` to `true` to skip native notifications when the active/focused window is already Pi.
 
 ### Gotify
 

package/packages/notify/commands.ts

@@ -14,7 +14,7 @@ import { NtfySetupOverlay } from "./tui/ntfy-setup.js";
 import { RecapModelSelectorOverlay } from "./tui/recap-model-selector.js";
 import { loadConfig } from "./settings.js";
 import { loadNtfyConfig } from "./ntfy-config.js";
-import { sendNativeNotification } from "./platforms/native.js";
+import { sendNativeNotification, SuppressedError } from "./platforms/native.js";
 import { sendGotifyNotification } from "./platforms/gotify.js";
 import { sendTelegramNotification } from "./platforms/telegram.js";
 import { sendNtfyNotification } from "./platforms/ntfy.js";
@@ -267,12 +267,17 @@ export function registerNotifyCommands(pi: ExtensionAPI): void {
           try {
             await sendNativeNotification(title, message, {
               windowsAppId: config.native.windowsAppId,
+              suppressWhenFocused: config.native.suppressWhenFocused,
             });
             results.push("✓ Native: sent");
           } catch (err) {
-            results.push(
-              `✗ Native: ${err instanceof Error ? err.message : "failed"}`
-            );
+            if (err instanceof SuppressedError) {
+              results.push("— Native: suppressed (window focused)");
+            } else {
+              results.push(
+                `✗ Native: ${err instanceof Error ? err.message : "failed"}`
+              );
+            }
           }
         }
 

package/packages/notify/events.ts

@@ -9,7 +9,7 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 import { UNIPI_EVENTS, emitEvent } from "@pi-unipi/core";
 import type { NotifyConfig, NotifyPlatform, NotifyDispatchResult } from "./types.js";
 import { loadNtfyConfig } from "./ntfy-config.js";
-import { sendNativeNotification } from "./platforms/native.js";
+import { sendNativeNotification, SuppressedError } from "./platforms/native.js";
 import { sendGotifyNotification } from "./platforms/gotify.js";
 import { sendTelegramNotification } from "./platforms/telegram.js";
 import { sendNtfyNotification } from "./platforms/ntfy.js";
@@ -184,6 +184,10 @@ export async function dispatchNotification(
         await sendToPlatform(platform, title, message, config, cwd);
         return { platform, success: true };
       } catch (err) {
+        // SuppressedError is intentional, not a failure
+        if (err instanceof SuppressedError) {
+          return { platform, success: true, suppressed: true };
+        }
         // Silently ignore — platform send failure is tracked in results.
         return {
           platform,
@@ -194,13 +198,18 @@ export async function dispatchNotification(
     })
   );
 
-  const allSuccess = results.length > 0 && results.every((r) => r.success);
+  const unsuppressed = results.filter((r) => !r.suppressed);
+  const allSuccess = results.length > 0 && unsuppressed.every((r) => r.success);
+  const suppressedPlatforms = results
+    .filter((r) => r.suppressed)
+    .map((r) => r.platform);
 
   // Emit notification sent event
   emitEvent(pi, UNIPI_EVENTS.NOTIFICATION_SENT, {
     eventType,
     platforms: enabledPlatforms,
     success: allSuccess,
+    ...(suppressedPlatforms.length > 0 && { suppressedPlatforms }),
     timestamp: new Date().toISOString(),
   });
 
@@ -219,6 +228,7 @@ async function sendToPlatform(
     case "native":
       await sendNativeNotification(title, message, {
         windowsAppId: config.native.windowsAppId,
+        suppressWhenFocused: config.native.suppressWhenFocused,
       });
       break;
     case "gotify":

package/packages/notify/platforms/focus-win.ts

@@ -0,0 +1,123 @@
+/**
+ * @pi-unipi/notify — Windows focus detection
+ *
+ * Checks whether the terminal window is the foreground (active) window
+ * by walking the WMI process tree upward from the current process PID
+ * and comparing each ancestor against the foreground window's owner PID.
+ *
+ * This approach works reliably across cmd, PowerShell, and Windows
+ * Terminal, unlike GetConsoleWindow which returns NULL in spawned
+ * child processes.
+ *
+ * Requires PowerShell (built-in on Windows 7+).
+ */
+
+import { execFile } from "child_process";
+import { writeFileSync, rmSync, mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+// ---------------------------------------------------------------------------
+// PowerShell script (embedded)
+// ---------------------------------------------------------------------------
+
+const POWERCHECK_SCRIPT = `
+param($targetPid)
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public class WinAPI {
+    [DllImport("user32.dll", SetLastError = false)]
+    public static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll", SetLastError = false)]
+    public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);
+}
+'@ | Out-Null
+$fgHwnd = [WinAPI]::GetForegroundWindow()
+[uint32]$fgPid = 0
+[void][WinAPI]::GetWindowThreadProcessId($fgHwnd, [ref]$fgPid)
+$curPid = $targetPid
+$maxDepth = 20
+while ($curPid -gt 0 -and $maxDepth-- -gt 0) {
+    if ($curPid -eq $fgPid) { Write-Host -NoNewline 'True'; exit }
+    $proc = Get-CimInstance -Class Win32_Process -Filter "ProcessId = $curPid" -ErrorAction SilentlyContinue | Select-Object -Property ParentProcessId
+    if (-not $proc) { break }
+    $curPid = $proc.ParentProcessId
+}
+Write-Host -NoNewline 'False'
+`;
+
+// ---------------------------------------------------------------------------
+// Cache — avoid spawning PowerShell on every check
+// ---------------------------------------------------------------------------
+
+let cached: { result: boolean; time: number } | null = null;
+const CACHE_TTL_MS = 500;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when the terminal window that owns the current process is
+ * the foreground (active) window on Windows.
+ *
+ * Works by:
+ *   1. Calling Win32 GetForegroundWindow + GetWindowThreadProcessId to
+ *      obtain the foreground window's owning PID.
+ *   2. Walking the WMI Win32_Process parent chain upward from
+ *      process.pid.
+ *   3. If any ancestor PID matches the foreground PID the terminal is
+ *      considered focused.
+ *
+ * The result is cached for 500 ms to avoid spawning PowerShell on rapid
+ * consecutive checks (e.g. batch notifications).
+ */
+export async function isWindowFocusedOnWindows(): Promise<boolean> {
+  const now = Date.now();
+  if (cached && now - cached.time < CACHE_TTL_MS) {
+    return cached.result;
+  }
+
+  let tmpDir: string | null = null;
+  try {
+    tmpDir = mkdtempSync(join(tmpdir(), "pi-focus-"));
+    const scriptPath = join(tmpDir, "check.ps1");
+    writeFileSync(scriptPath, POWERCHECK_SCRIPT, "utf-8");
+
+    const stdout = await new Promise<string>((resolve, reject) => {
+      execFile(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-ExecutionPolicy",
+          "Bypass",
+          "-File",
+          scriptPath,
+          String(process.pid),
+        ],
+        { timeout: 5000, encoding: "utf-8" },
+        (err, out) => {
+          if (err) reject(err);
+          else resolve(out);
+        }
+      );
+    });
+
+    cached = { result: stdout.trim() === "True", time: Date.now() };
+    return cached.result;
+  } catch {
+    // Detection failure → safe default: assume NOT focused (don't suppress)
+    cached = { result: false, time: Date.now() };
+    return false;
+  } finally {
+    if (tmpDir) {
+      try {
+        rmSync(tmpDir, { recursive: true });
+      } catch {
+        // Temp file cleanup is non-critical
+      }
+    }
+  }
+}