privateer-agent 0.14.1 → 0.14.2

package/README.md

@@ -402,8 +402,12 @@ including a new agent the moment its window opens in front. The window you left
 its mic. (That's [privateer-speak](https://www.npmjs.com/package/privateer-speak)'s focus
 awareness; it needs a terminal that reports focus.)
 
-Works in **macOS Terminal**, **iTerm2**, and inside **tmux** on any platform; other terminals
-get told so. macOS may ask once for permission to let the terminal control itself. Names are
+Works in **macOS Terminal**, **iTerm2**, **Git Bash's own window (mintty)** on Windows, and
+inside **tmux** on any platform; other terminals get told so. macOS may ask once for permission
+to let the terminal control itself. In Git Bash, new windows are mintty windows like the one
+you started in, and since mintty doesn't tell the program inside when it gains or loses focus,
+Privateer watches which window Windows has in front (a small PowerShell loop, one per window)
+so the voice still follows you. Names are
 shared across every Privateer on the machine (`~/.privateer/terminals.json`), and a window
 that's been closed drops off the list on its own.
 

package/extensions/privateer-speak.ts

@@ -61,7 +61,7 @@ import {
 } from "privateer-speak";
 import { apiRequest, hasCredentials } from "../src/auth/privateer.ts";
 import { globalDir } from "../src/config/paths.ts";
-import { thisTerminalIsFront } from "../src/terminals/index.ts";
+import { thisTerminalIsFront, watchThisTerminalFocus } from "../src/terminals/index.ts";
 import { VOICE_DESCRIPTIONS } from "./speak-voices.data.ts";
 
 const QWEN3_TTS_VOICES = ["serena", "aiden", "dylan", "eric", "ono_anna", "ryan", "sohee", "uncle_fu", "vivian"];
@@ -362,10 +362,14 @@ export default function privateerSpeak(pi: any): void {
   // isFocused: a window that has just started (say, one the agent opened with the
   // terminal tool) asks Terminal/iTerm2 whether it's in front, so a hands-free mode
   // carries on in the new agent without a keypress — see src/terminals/.
+  // watchFocus: Git Bash's window (mintty) never tells the program inside when it gains
+  // or loses focus, so there Windows is watched instead, or the mic wouldn't follow you
+  // between windows.
   makePiSpeakExtension({
     configFile: join(globalDir(), "speak.json"),
     voiceCommands: VOICE_COMMANDS,
     isFocused: thisTerminalIsFront,
+    watchFocus: watchThisTerminalFocus,
   })(pi);
 }
 

package/extensions/privateer-truncation.ts

@@ -0,0 +1,43 @@
+// Keep the agent going when a reply is cut off at the output limit.
+//
+// A run that ends on a full-budget length stop ("Response was truncated before
+// completion.") just stops in stock pi — the agent abandons the task until the user
+// types "continue". This queues that follow-up for them, at most MAX_AUTO_CONTINUES
+// times in a row. The decision, and why it is shaped this way, lives in
+// src/engine/truncationRecovery.ts.
+
+import { MAX_AUTO_CONTINUES, decideTruncationRecovery } from "../src/engine/truncationRecovery.ts";
+
+export default function privateerTruncation(pi: any): void {
+  let consecutive = 0;
+
+  // Something the user typed starts a fresh count: giving up once must not disarm
+  // recovery for the rest of the session.
+  pi.on("input", () => {
+    consecutive = 0;
+  });
+
+  pi.on("agent_end", (ev: any, ctx: any) => {
+    const decision = decideTruncationRecovery(ev?.messages, Number(ctx?.model?.maxTokens) || 0, consecutive);
+    if (decision.action === "none") {
+      consecutive = 0;
+      return;
+    }
+    if (decision.action === "give-up") {
+      ctx?.ui?.notify?.(
+        `The reply was cut off at the output limit ${MAX_AUTO_CONTINUES + 1} times in a row — stopped. ` +
+          `Type "continue" to try again, lower the thinking level (shift+tab), or pick another model.`,
+        "warning",
+      );
+      return;
+    }
+    consecutive = decision.attempt;
+    ctx?.ui?.notify?.(`Reply cut off at the output limit — continuing (${decision.attempt}/${MAX_AUTO_CONTINUES}).`, "info");
+    // Queued from agent_end while the run is still active, so pi continues it in the
+    // same run (agent-session _handlePostAgentRun) instead of waiting for the user.
+    pi.sendMessage(
+      { customType: "privateer-truncation", content: decision.prompt, display: true, details: { attempt: decision.attempt } },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "pi-privacy": "0.14.1",
     "pi-subagents": "0.70.0",
     "picomatch": "4.0.5",
-    "privateer-speak": "0.7.0",
+    "privateer-speak": "0.8.0",
     "privateer-workflow": "0.1.0",
     "tinfoil": "1.1.11",
     "tsx": "4.23.0",

package/src/config/moatManifest.json

@@ -23,6 +23,7 @@
     { "entry": "extensions/privateer-terminals.ts", "name": "privateer-terminals", "note": "named terminal windows — the terminal tool + /term to switch between them" },
     { "entry": "extensions/privateer-hints.ts", "name": "privateer-hints", "note": "rotating tips in the working line + /hints" },
     { "entry": "extensions/privateer-update.ts", "name": "privateer-update", "note": "tool pack updates in place — banner flag + /update" },
+    { "entry": "extensions/privateer-truncation.ts", "name": "privateer-truncation", "note": "picks the task back up when a reply is cut off at the output limit" },
     { "entry": "extensions/privateer-fresh.ts", "name": "privateer-fresh", "note": "/fresh — replace the agent with a new one and stop everything it started" },
     { "entry": "extensions/privateer-speak.ts", "name": "privateer-speak", "note": "spoken responses (/speak) + voice input (/talk) — pi-speak + confidential account TTS/STT" },
     { "entry": "extensions/privateer-web.ts", "name": "privateer-web", "note": "web_search/web_fetch — account search when signed in, else the user's own provider (rpiv-web-tools); crypto_lookup — account market data, in both cases" },

package/src/config/whatsNew.json

@@ -1,10 +1,10 @@
 {
   "$comment": "The banner's What's New list, newest first: the two to four things a returning user should notice, not a changelog. `reviewedFor` is the release this list was last looked at for. A release can't ship until it equals package.json's version (scripts/check-whats-new.mjs, run by `npm test` and by release.yml before anything builds), so every release, patches included, is a deliberate look at this list. If nothing new is worth a line, bumping `reviewedFor` alone is the answer. `since` is the release an entry arrived in. `cmd` is shown in the accent colour.",
-  "reviewedFor": "0.14.1",
+  "reviewedFor": "0.14.2",
   "items": [
+    { "text": "A reply cut off at the output limit picks back up on its own", "since": "0.14.2" },
     { "text": "Chat channels as a login service: privateer channels install", "since": "0.14.1" },
     { "text": "Hand off sensitive files: privateer --private", "since": "0.14.0" },
-    { "text": "Open and switch named terminals —", "cmd": "/term", "since": "0.13.0" },
-    { "text": "Voice follows the window you're in", "since": "0.13.0" }
+    { "text": "Open and switch named terminals —", "cmd": "/term", "since": "0.13.0" }
   ]
 }

package/src/engine/truncationRecovery.ts

@@ -0,0 +1,91 @@
+// What to do when a run ends on a reply the model never finished.
+//
+// A provider that stops a reply with `finish_reason: "length"` hit the turn's output
+// cap. The TUI renders it as "Response was truncated before completion." and pi then
+// does one of two things:
+//
+//   - output ended BELOW the model's maxTokens: pi reads it as context pressure and
+//     compacts and retries the turn once (agent-session _checkCompaction,
+//     isRecoverableLength). That case is pi's, and this module stays out of it.
+//   - output used the WHOLE budget: pi treats it as final and the run just ends. The
+//     agent stops mid-task with nothing to resume it but the user typing "continue".
+//
+// The second case is what real sessions hit, and nearly always the same way: a
+// thinking model spends the entire budget reasoning (measured: z-ai/glm-5.3-flash,
+// 16384 of 16384 output tokens, 45–67k characters of reasoning, no text and no tool
+// call — nine times across one user's logs). Raising maxTokens to the model's real cap
+// (providers/account.ts) makes that rarer; this makes it recoverable when it happens.
+//
+// So: when a run ends on a full-budget length stop, queue one follow-up asking the
+// model to pick up where it was cut off, and keep its reasoning short. Pi continues a
+// message queued from an agent_end handler inside the same run (_handlePostAgentRun →
+// hasQueuedMessages), so headless `-p` runs wait for it too.
+//
+// Bounded: at most MAX_AUTO_CONTINUES in a row. A model that truncates every time
+// would otherwise loop forever, billing a full budget per lap. Any reply that ends
+// some other way resets the count.
+//
+// IMPORT-SAFETY: no Pi imports — the shapes below are the few fields read.
+
+export const MAX_AUTO_CONTINUES = 2;
+
+export interface TruncationAssistant {
+  role?: string;
+  stopReason?: string;
+  usage?: { output?: number };
+  content?: { type?: string }[];
+}
+
+export type TruncationDecision =
+  | { action: "none" }
+  | { action: "continue"; attempt: number; prompt: string }
+  | { action: "give-up" };
+
+export function lastAssistant(messages: unknown): TruncationAssistant | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i] as TruncationAssistant | undefined;
+    if (m?.role === "assistant") return m;
+  }
+  return undefined;
+}
+
+/**
+ * Whether a length stop used the model's whole output budget. Mirrors the negation of
+ * pi-ai's isRecoverableLength: below the budget is pi's compact-and-retry, at it is
+ * ours. An unknown budget (0) means we cannot tell, so we leave it alone.
+ */
+export function isFullBudgetLengthStop(message: TruncationAssistant | undefined, modelMaxTokens: number): boolean {
+  if (message?.stopReason !== "length") return false;
+  if (!(modelMaxTokens > 0)) return false;
+  const output = message.usage?.output;
+  return typeof output === "number" && output >= modelMaxTokens;
+}
+
+/**
+ * The follow-up text. Says what happened in terms the model can act on: a cut-off
+ * spent on reasoning needs a terser plan, a cut-off mid-tool-call needs the call
+ * re-issued (its arguments were incomplete and never ran).
+ */
+export function continuationPrompt(message: TruncationAssistant): string {
+  const kinds = new Set((message.content ?? []).map((c) => c?.type));
+  const base = "Your previous reply hit the output limit and was cut off before it finished.";
+  if (kinds.has("toolCall")) {
+    return `${base} The tool call at the end was incomplete and did not run — issue it again in full. Keep any reasoning brief.`;
+  }
+  if (!kinds.has("text")) {
+    return `${base} It was spent entirely on reasoning. Don't restate it: keep thinking short and go straight to the next tool call or your answer.`;
+  }
+  return `${base} Continue exactly where you left off, without repeating what you already wrote. Keep any reasoning brief.`;
+}
+
+export function decideTruncationRecovery(
+  messages: unknown,
+  modelMaxTokens: number,
+  consecutive: number,
+): TruncationDecision {
+  const last = lastAssistant(messages);
+  if (!isFullBudgetLengthStop(last, modelMaxTokens)) return { action: "none" };
+  if (consecutive >= MAX_AUTO_CONTINUES) return { action: "give-up" };
+  return { action: "continue", attempt: consecutive + 1, prompt: continuationPrompt(last!) };
+}

package/src/providers/account.ts

@@ -100,6 +100,27 @@ function validContextWindow(value: unknown): number | undefined {
     : undefined;
 }
 
+// What to ask for per turn when the server publishes no output cap for a model — the
+// flat value the whole catalog used to be registered with, so "unpublished" behaves
+// exactly as it always has.
+const DEFAULT_MAX_OUTPUT_TOKENS = 16384;
+
+// The server's own ceiling on a proxied turn (treeview inferenceService
+// PROXY_MAX_COMPLETION_TOKENS). Asking past it buys nothing — the proxy sizes its
+// balance gate to at most this — so a published cap above it is clamped here.
+const ACCOUNT_MAX_OUTPUT_TOKENS = 32000;
+
+// Below this a turn cannot fit a complete tool call; same floor pi-ai uses for an
+// answer (contextBudget.ts MIN_ANSWER_TOKENS). A smaller published cap is treated as
+// garbled rather than strangling every turn.
+const MIN_PUBLISHED_MAX_OUTPUT = 1024;
+
+function validMaxOutputTokens(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= MIN_PUBLISHED_MAX_OUTPUT
+    ? Math.min(Math.floor(value), ACCOUNT_MAX_OUTPUT_TOKENS)
+    : undefined;
+}
+
 function seedModel(id: string) {
   return {
     id,
@@ -119,7 +140,13 @@ function seedModel(id: string) {
     // that under-states the model's real one therefore throttles the answer — and
     // used to collapse it to a single token — while the model still has room.
     contextWindow: accountContextWindow(id) ?? DEFAULT_CONTEXT_WINDOW,
-    maxTokens: 16384,
+    // The model's real output cap when published. Not cosmetic either: reasoning and
+    // the answer share this one budget, and pi only compact-and-retries a length stop
+    // that ended BELOW it — a thinking model that spends all of a too-small budget
+    // reasoning ends the run with "Response was truncated before completion."
+    // (measured: glm-5.3-flash spending all 16384 on 50k+ chars of reasoning, whose
+    // real cap is far higher). See also ext/truncationRecovery.ts.
+    maxTokens: accountMaxOutputTokens(id) ?? DEFAULT_MAX_OUTPUT_TOKENS,
   };
 }
 
@@ -296,14 +323,19 @@ function saveCachedCatalog(infos: AccountModelInfo[]): void {
     mkdirSync(globalDir(), { recursive: true });
     const kept = infos.slice(0, CATALOG_CACHE_MAX);
     const windows: Record<string, number> = {};
+    const maxOutputs: Record<string, number> = {};
     for (const info of kept) {
       if (info.contextWindow !== undefined) windows[info.id] = info.contextWindow;
+      if (info.maxOutputTokens !== undefined) maxOutputs[info.id] = info.maxOutputTokens;
     }
     const payload = {
       v: 2,
       fetchedAt: new Date().toISOString(),
       ids: kept.map((info) => info.id),
       windows,
+      // Same reasoning as `windows`: a capability needed at launch. Absent in older
+      // files, which then fall back per model.
+      maxOutputs,
     };
     writeFileSync(catalogCachePath(), JSON.stringify(payload) + "\n", "utf8");
     forgetCachedContextWindows();
@@ -316,33 +348,42 @@ function saveCachedCatalog(infos: AccountModelInfo[]): void {
 // the catalog on every registration, and the catalog re-registers whenever the shim
 // state changes — re-reading and re-parsing a 284-entry file each time would turn a
 // cheap lookup into hundreds of syscalls on the launch path.
-let cachedWindows: Map<string, number> | null = null;
+let cachedCapabilities: { windows: Map<string, number>; maxOutputs: Map<string, number> } | null = null;
 
-function cachedContextWindows(): Map<string, number> {
-  if (cachedWindows) return cachedWindows;
-  cachedWindows = new Map();
+function cachedCapabilityMaps(): { windows: Map<string, number>; maxOutputs: Map<string, number> } {
+  if (cachedCapabilities) return cachedCapabilities;
+  cachedCapabilities = { windows: new Map(), maxOutputs: new Map() };
   try {
     const path = catalogCachePath();
     if (existsSync(path)) {
-      const parsed = JSON.parse(readFileSync(path, "utf8")) as { windows?: unknown };
-      // A v1 file has no `windows` at all; every id then falls back, exactly as before.
-      if (parsed.windows && typeof parsed.windows === "object") {
-        for (const [id, value] of Object.entries(parsed.windows as Record<string, unknown>)) {
-          const window = validContextWindow(value);
-          if (window !== undefined && cachedWindows.size < CATALOG_CACHE_MAX) cachedWindows.set(id, window);
-        }
-      }
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as { windows?: unknown; maxOutputs?: unknown };
+      // A v1 file has no `windows` (and an older v2 no `maxOutputs`); every id then
+      // falls back, exactly as before. Re-validated on read: the file is input too.
+      readCapability(parsed.windows, validContextWindow, cachedCapabilities.windows);
+      readCapability(parsed.maxOutputs, validMaxOutputTokens, cachedCapabilities.maxOutputs);
     }
   } catch {
-    /* absent, unreadable, or garbage — every model just uses the fallback window */
+    /* absent, unreadable, or garbage — every model just uses the fallbacks */
+  }
+  return cachedCapabilities;
+}
+
+function readCapability(raw: unknown, valid: (value: unknown) => number | undefined, into: Map<string, number>): void {
+  if (!raw || typeof raw !== "object") return;
+  for (const [id, value] of Object.entries(raw as Record<string, unknown>)) {
+    const n = valid(value);
+    if (n !== undefined && into.size < CATALOG_CACHE_MAX) into.set(id, n);
   }
-  return cachedWindows;
+}
+
+function cachedContextWindows(): Map<string, number> {
+  return cachedCapabilityMaps().windows;
 }
 
 // Drop the memo so the next read sees what was just written (and so a test can rewrite
 // the cache between assertions).
 function forgetCachedContextWindows(): void {
-  cachedWindows = null;
+  cachedCapabilities = null;
 }
 
 export function loadCachedCatalogIds(): string[] {
@@ -408,6 +449,9 @@ export interface AccountModelInfo {
   // Absent means "unknown" — seedModel falls back to DEFAULT_CONTEXT_WINDOW rather
   // than to a guess, so an older server behaves exactly as before.
   contextWindow?: number;
+  // The server's published per-turn output cap, already clamped to the proxy's
+  // ceiling. Absent means unknown — seedModel falls back to DEFAULT_MAX_OUTPUT_TOKENS.
+  maxOutputTokens?: number;
 }
 
 // The set of tier strings pi-privacy defines (posture/tiers.ts). We only trust a
@@ -454,6 +498,13 @@ export function accountContextWindow(id: string): number | undefined {
   return accountWindowMap.get(id) ?? cachedContextWindows().get(id);
 }
 
+// Published output caps, keyed by modelId — live catalog first, then the disk cache.
+const accountMaxOutputMap = new Map<string, number>();
+
+export function accountMaxOutputTokens(id: string): number | undefined {
+  return accountMaxOutputMap.get(id) ?? cachedCapabilityMaps().maxOutputs.get(id);
+}
+
 // The server-asserted baseline tier for an account model, or undefined if we haven't
 // seen it in a catalog fetch. Used by the /models picker (privateer-models.ts).
 export function accountBaselineTier(modelId: string): PrivacyTier | undefined {
@@ -483,7 +534,7 @@ export async function fetchAccountCatalog(): Promise<AccountModelInfo[]> {
       infos = fallback();
     } else {
       const data = (await res.json()) as {
-        models?: { modelId?: string; privacy?: { tier?: string }; contextLength?: unknown }[];
+        models?: { modelId?: string; privacy?: { tier?: string }; contextLength?: unknown; maxCompletionTokens?: unknown }[];
       };
       const parsed = (data.models ?? [])
         .map((m): AccountModelInfo | null =>
@@ -495,6 +546,7 @@ export async function fetchAccountCatalog(): Promise<AccountModelInfo[]> {
                 // absent entirely on a server older than the field — both mean
                 // "unknown", and validContextWindow collapses them to undefined.
                 contextWindow: validContextWindow(m.contextLength),
+                maxOutputTokens: validMaxOutputTokens(m.maxCompletionTokens),
               }
             : null,
         )
@@ -511,9 +563,11 @@ export async function fetchAccountCatalog(): Promise<AccountModelInfo[]> {
   }
   accountTierMap.clear();
   accountWindowMap.clear();
+  accountMaxOutputMap.clear();
   for (const info of infos) {
     accountTierMap.set(info.id, info.tier);
     if (info.contextWindow !== undefined) accountWindowMap.set(info.id, info.contextWindow);
+    if (info.maxOutputTokens !== undefined) accountMaxOutputMap.set(info.id, info.maxOutputTokens);
   }
   return infos;
 }

package/src/terminals/backends.ts

@@ -14,20 +14,28 @@
 // easier to match and are worthless as identity: the shell rewrites them on every
 // prompt.
 //
-// THREE BACKENDS, ONE ON PURPOSE PER PLACE. tmux wins whenever we are inside it,
-// because there the "window" the user sees is tmux's, whatever app draws it. Outside
-// tmux: macOS Terminal and iTerm2 through AppleScript. Everything else (Ghostty,
-// kitty, WezTerm, Linux and Windows terminals with no tmux) gets a clear "not here"
-// rather than a guess: focusing a window by name on X11/Wayland/Windows needs a
-// window manager contract we can't count on, and tmux runs everywhere.
+// ONE BACKEND ON PURPOSE PER PLACE. tmux wins whenever we are inside it, because there
+// the "window" the user sees is tmux's, whatever app draws it. Outside tmux: macOS
+// Terminal and iTerm2 through AppleScript, and Git Bash's own window (mintty) on Windows
+// through PowerShell. Everything else (Ghostty, kitty, WezTerm, Windows Terminal, Linux
+// terminals with no tmux) gets a clear "not here" rather than a guess: focusing a window
+// by name there needs a window manager contract we can't count on, and tmux runs
+// everywhere.
+//
+// On Windows there is no tty to go by, so a mintty window's id is its Windows process
+// id: each window is one mintty.exe, and a Privateer inside finds it by walking up its
+// parent processes.
 //
 // AppleScript runs as the terminal app controlling ITSELF (Privateer is a child of the
 // window it draws in). Terminal does this without an Automation prompt (verified);
 // iTerm2 is untested here and may ask once.
 
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
-export type TerminalApp = "tmux" | "Apple_Terminal" | "iTerm.app";
+export type TerminalApp = "tmux" | "Apple_Terminal" | "iTerm.app" | "mintty";
 
 export interface OpenRequest {
   name: string;
@@ -54,6 +62,12 @@ export interface TerminalBackend {
   selfId(): Promise<string | undefined>;
   /** Is this window the one in front, app and all? undefined when it can't tell. */
   isFront(id: string): Promise<boolean | undefined>;
+  /**
+   * Call `onChange` each time the window with this id comes to the front or goes
+   * behind. Only where the terminal can't say so itself (mintty: see watchFront below).
+   * Returns what stops watching.
+   */
+  watchFront?(id: string, onChange: (front: boolean) => void): () => void;
 }
 
 /** Run a program and hand back stdout; injectable so tests can see the exact calls. */
@@ -355,6 +369,168 @@ export function tmux(exec: Exec = execProgram, env: NodeJS.ProcessEnv = process.
   };
 }
 
+// ── mintty (Git Bash on Windows) ────────────────────────────────────────────
+
+/** Start a program in its own window and hand back its process id. Injectable for tests. */
+export type Launch = (file: string, args: string[], opts: { cwd: string; env: NodeJS.ProcessEnv }) => Promise<number>;
+
+export const launchDetached: Launch = (file, args, opts) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(file, args, { ...opts, detached: true, stdio: "ignore" });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref();
+      if (child.pid) resolve(child.pid);
+      else reject(new Error(`${file} started without a process id`));
+    });
+  });
+
+/**
+ * PowerShell, handed its script base64-encoded: the one way to get quotes, braces and
+ * newlines through Windows' command line untouched.
+ */
+export function powershellArgs(script: string): string[] {
+  return ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")];
+}
+
+// The few user32 calls PowerShell can't make on its own.
+const USER32 = `
+Add-Type -Namespace PV -Name U -MemberDefinition @'
+[DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+[DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+[DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+[DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int cmd);
+[DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+[DllImport("user32.dll")] public static extern void keybd_event(byte key, byte scan, uint flags, UIntPtr extra);
+'@
+function FrontPid { $p = [uint32]0; [PV.U]::GetWindowThreadProcessId([PV.U]::GetForegroundWindow(), [ref]$p) | Out-Null; $p }
+`;
+
+/** Walk up from `pid` to the first mintty.exe; prints "<pid>|<exe path>" or nothing. */
+export const minttyAncestorScript = (pid: number): string => `
+$all = @{}
+foreach ($p in Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,Name,ExecutablePath) { $all[[int]$p.ProcessId] = $p }
+$id = ${Math.trunc(pid)}
+for ($i = 0; $i -lt 32 -and $all.ContainsKey($id); $i++) {
+  $p = $all[$id]
+  if ($p.Name -ieq 'mintty.exe') { Write-Output "$($p.ProcessId)|$($p.ExecutablePath)"; exit }
+  $id = [int]$p.ParentProcessId
+}`;
+
+/**
+ * Bring a window forward. Windows only lets the program in front hand the foreground
+ * over; a tap of Alt is the long-standing way for a helper to be allowed to.
+ */
+export const minttyFocusScript = (pid: number): string => `${USER32}
+$p = Get-Process -Id ${Math.trunc(pid)} -ErrorAction SilentlyContinue
+if (-not $p -or $p.MainWindowHandle -eq 0) { Write-Output 'missing'; exit }
+$h = $p.MainWindowHandle
+if ([PV.U]::IsIconic($h)) { [PV.U]::ShowWindow($h, 9) | Out-Null }
+[PV.U]::keybd_event(0x12, 0, 0, [UIntPtr]::Zero); [PV.U]::keybd_event(0x12, 0, 2, [UIntPtr]::Zero)
+[PV.U]::SetForegroundWindow($h) | Out-Null
+Write-Output 'ok'`;
+
+export const frontPidScript = `${USER32}
+Write-Output (FrontPid)`;
+
+/**
+ * Print the foreground window's process id whenever it changes, until `owner` exits —
+ * a process left behind on Windows isn't ended with its parent. 0 is skipped: there is
+ * no foreground window for a moment during alt-tab, and reporting it would pause the
+ * mic mid-word.
+ */
+export const frontWatchScript = (owner: number): string => `${USER32}
+$last = -1; $n = 0
+while ($true) {
+  $p = FrontPid
+  if ($p -ne 0 -and $p -ne $last) { $last = $p; [Console]::Out.WriteLine($p); [Console]::Out.Flush() }
+  if ((++$n % 10) -eq 0 -and -not (Get-Process -Id ${Math.trunc(owner)} -ErrorAction SilentlyContinue)) { exit }
+  Start-Sleep -Milliseconds 200
+}`;
+
+/** mintty's CSV process list → the ids of every mintty window. */
+export function parseTasklist(out: string): Set<string> {
+  const ids = new Set<string>();
+  for (const line of out.split(/\r?\n/)) {
+    const m = /^"mintty\.exe","(\d+)"/i.exec(line.trim());
+    if (m) ids.add(m[1]!);
+  }
+  return ids;
+}
+
+/** A Windows path as Git Bash reads it: forward slashes. */
+const msysPath = (p: string): string => p.replace(/\\/g, "/");
+
+export function mintty(
+  exec: Exec = execProgram,
+  launch: Launch = launchDetached,
+  env: NodeJS.ProcessEnv = process.env,
+  scripts: { dir: string; write: (path: string, body: string) => void } = { dir: tmpdir(), write: (p, b) => writeFileSync(p, b, { mode: 0o600 }) },
+): TerminalBackend {
+  const ps = (script: string) => exec("powershell.exe", powershellArgs(script));
+  let self: Promise<{ pid: string; exe: string } | undefined> | undefined;
+  const findSelf = () =>
+    (self ??= ps(minttyAncestorScript(process.pid))
+      .then((out) => {
+        const [pid, exe] = out.trim().split("|");
+        return pid && /^\d+$/.test(pid) ? { pid, exe: exe?.trim() || "mintty.exe" } : undefined;
+      })
+      .catch(() => undefined));
+  const live = async () => parseTasklist(await exec("tasklist", ["/FI", "IMAGENAME eq mintty.exe", "/FO", "CSV", "/NH"]));
+  return {
+    app: "mintty",
+    label: "Git Bash",
+    async open(req) {
+      const exe = (await findSelf())?.exe ?? "mintty.exe";
+      const shell = env.SHELL || "/usr/bin/bash";
+      // The command goes in a script file rather than on mintty's command line, where
+      // Windows and Cygwin each have their own idea of quoting. It deletes itself, runs,
+      // and leaves a login shell behind, so the window outlives the command.
+      const file = join(scripts.dir, `privateer-term-${process.pid}-${Date.now()}.sh`);
+      scripts.write(file, `rm -f "$0"\n${shellLine(req.cwd, req.command)}\nexec ${shQuote(shell)} -l\n`);
+      // CHERE_INVOKING keeps Git Bash's login profile from moving the shell to $HOME.
+      const pid = await launch(exe, ["-t", req.name, "-e", shell, "-l", msysPath(file)], {
+        cwd: req.cwd,
+        env: { ...env, CHERE_INVOKING: "1" },
+      });
+      return String(pid);
+    },
+    async focus(id) {
+      return (await ps(minttyFocusScript(Number(id)))).trim() === "ok";
+    },
+    async close(id) {
+      if (!(await live()).has(id)) return false;
+      // /T takes the shell and whatever it runs along with the window.
+      await exec("taskkill", ["/PID", id, "/T", "/F"]);
+      return true;
+    },
+    live,
+    selfId: async () => (await findSelf())?.pid,
+    async isFront(id) {
+      const out = (await ps(frontPidScript)).trim();
+      return /^\d+$/.test(out) ? out === id : undefined;
+    },
+    watchFront(id, onChange) {
+      const child = spawn("powershell.exe", powershellArgs(frontWatchScript(process.pid)), { stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+      let last: boolean | undefined;
+      let buf = "";
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk: string) => {
+        buf += chunk;
+        const lines = buf.split(/\r?\n/);
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!/^\d+$/.test(line.trim())) continue;
+          const front = line.trim() === id;
+          if (front !== last) onChange((last = front));
+        }
+      });
+      child.on("error", () => undefined); // no PowerShell: focus just isn't tracked
+      return () => void child.kill();
+    },
+  };
+}
+
 /**
  * The backend for the window this process is in, or why there isn't one. tmux first:
  * inside it, TERM_PROGRAM names the app that draws tmux, not the thing we can drive.
@@ -367,10 +543,11 @@ export function detectBackend(
   if (env.TMUX) return tmux(exec, env);
   if (platform === "darwin" && env.TERM_PROGRAM === "Apple_Terminal") return appleTerminal(exec);
   if (platform === "darwin" && env.TERM_PROGRAM === "iTerm.app") return iTerm(exec);
+  if (platform === "win32" && env.TERM_PROGRAM === "mintty") return mintty(exec);
   const where = env.TERM_PROGRAM ? `${env.TERM_PROGRAM}` : platform === "win32" ? "this Windows terminal" : "this terminal";
   return {
     unsupported:
-      `Named terminals work inside tmux, macOS Terminal and iTerm2 — not in ${where}. ` +
-      `Run privateer inside tmux to use them here.`,
+      `Named terminals work inside tmux, macOS Terminal, iTerm2 and Git Bash's own window (mintty) — not in ${where}. ` +
+      (platform === "win32" ? `Run privateer from the Git Bash window to use them here.` : `Run privateer inside tmux to use them here.`),
   };
 }

package/src/terminals/index.ts

@@ -169,6 +169,29 @@ export async function thisTerminalIsFront(): Promise<boolean | undefined> {
   }
 }
 
+/**
+ * Report whether this window is in front each time that changes, for terminals that
+ * can't tell the program inside themselves (mintty on Windows — see backends.ts). For
+ * privateer-speak's watchFocus; elsewhere the terminal's own focus reports do this, and
+ * it watches nothing.
+ */
+export function watchThisTerminalFocus(report: (front: boolean) => void): () => void {
+  const b = backend();
+  if ("unsupported" in b || !b.watchFront) return () => undefined;
+  let stop: (() => void) | undefined;
+  let stopped = false;
+  void b
+    .selfId()
+    .then((id) => {
+      if (id && !stopped) stop = b.watchFront!(id, report);
+    })
+    .catch(() => undefined);
+  return () => {
+    stopped = true;
+    stop?.();
+  };
+}
+
 export interface TerminalListing {
   records: TerminalRecord[];
   selfId?: string;

package/src/tools/terminal.ts

@@ -33,7 +33,8 @@ export const terminalToolDefinition = {
     "`list` shows every named terminal and marks this one. `close` closes a window and ends what runs in it. " +
     "You can NOT read a terminal's output: for commands whose output you need, use bash or a background task. " +
     "Use this when the user wants to watch or use something themselves, or asks to switch terminals. " +
-    "Works in macOS Terminal, iTerm2, and inside tmux.",
+    "Works in macOS Terminal, iTerm2, Git Bash's own window (mintty) on Windows, and inside tmux. " +
+    "Don't improvise with bash (`start`, `mintty`, `open -a`) when this says it can't: tell the user instead.",
   parameters: Type.Object({
     action: Type.Union(ACTIONS.map((a) => Type.Literal(a)), { description: "What to do." }),
     name: Type.Optional(