tau-all-agent 0.1.6 → 0.3.0

package/extensions/{branch-term.ts → branch-term/index.ts}

@@ -1,14 +1,7 @@
 import { spawn, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
-import * as path from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import {
-  CURRENT_SESSION_VERSION,
-  SessionManager,
-  highlightCode,
-  type SessionHeader,
-} from "@earendil-works/pi-coding-agent";
+import { SessionManager, highlightCode, type SessionHeader } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 
 const TERMINAL_FLAG = "branch-term";
@@ -46,7 +39,7 @@ const TMUX_LAYOUT_CONFIG: Record<
 };
 
 function getStringFlag(pi: ExtensionAPI, flagName: string): string | undefined {
-  const value = pi.getFlag(`--${flagName}`);
+  const value = pi.getFlag(flagName);
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;
@@ -55,7 +48,7 @@ function getStringFlag(pi: ExtensionAPI, flagName: string): string | undefined {
 function parseTmuxLayout(value: string | undefined): TmuxLayout | undefined {
   if (!value) return undefined;
   const normalized = value.trim().toLowerCase();
-  if (normalized in TMUX_LAYOUT_CONFIG) {
+  if (Object.hasOwn(TMUX_LAYOUT_CONFIG, normalized)) {
     return normalized as TmuxLayout;
   }
   return undefined;
@@ -103,73 +96,23 @@ function getBranchArgumentCompletions(
   return matches;
 }
 
-function renderTerminalCommand(template: string, cwd: string, sessionFile: string): string {
-  let command = template;
-  command = command.split("{cwd}").join(cwd);
-
-  if (command.includes("{command}")) {
-    const piCommand = `pi --session ${shellQuote(sessionFile)}`;
-    command = command.split("{command}").join(piCommand);
-  }
-
-  if (command.includes("{session}")) {
-    command = command.split("{session}").join(sessionFile);
-  }
-
-  if (template.includes("{command}") || template.includes("{session}")) {
-    return command;
-  }
-
-  return `${command} ${sessionFile}`;
+function renderTerminalCommand(template: string): string {
+  // Paths stay data even when they contain shell syntax or placeholder-like text.
+  const command = template.replace(
+    /\{(cwd|session|command)\}/g,
+    (_match, name: string) => `"$TAU_BRANCH_${name.toUpperCase()}"`,
+  );
+  return /\{(command|session)\}/.test(template) ? command : `${command} "$TAU_BRANCH_SESSION"`;
 }
 
-function spawnDetached(command: string, args: string[], onError?: (error: Error) => void): void {
-  const child = spawn(command, args, { detached: true, stdio: "ignore" });
-  child.unref();
-  if (onError) child.on("error", onError);
-}
+// Shared outside the factory so detached children cannot retain a session through this listener.
+function ignoreDetachedLauncherError(): void {}
 
 function shellQuote(value: string): string {
   if (value.length === 0) return "''";
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
-function escapeForDoubleQuotes(value: string): string {
-  return value.replace(/(["\\$`!])/g, "\\$1");
-}
-
-function shellQuoteCompact(value: string): string {
-  const home = process.env.HOME;
-  if (!home) return shellQuote(value);
-
-  if (value === home) return "$HOME";
-
-  if (value.startsWith(`${home}/`)) {
-    const suffix = value.slice(home.length + 1);
-    return `"$HOME/${escapeForDoubleQuotes(suffix)}"`;
-  }
-
-  return shellQuote(value);
-}
-
-function parseSessionIdFromFile(sessionFile: string): string | undefined {
-  const fileName = path.basename(sessionFile, ".jsonl");
-  const separatorIndex = fileName.lastIndexOf("_");
-  if (separatorIndex <= 0) return undefined;
-
-  const candidate = fileName.slice(separatorIndex + 1);
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(candidate)
-    ? candidate
-    : undefined;
-}
-
-function formatResumeSessionArgument(sessionFile: string): string {
-  const sessionId = parseSessionIdFromFile(sessionFile);
-  if (sessionId) return sessionId;
-
-  return shellQuoteCompact(sessionFile);
-}
-
 function runClipboardCommand(command: string, args: string[], text: string): boolean {
   try {
     const result = spawnSync(command, args, {
@@ -214,7 +157,7 @@ function showCommandMessage(
   command: string,
 ): void {
   const copiedToClipboard = copyToClipboard(command);
-  if (!ctx.hasUI) {
+  if (ctx.mode === "print") {
     console.log(formatCommandMessageIntro(intro, copiedToClipboard));
     console.log(command);
     return;
@@ -241,26 +184,32 @@ function hasValidSessionFile(sessionFile: string): boolean {
   }
 }
 
-function createFreshSessionFile(cwd: string, sessionDir: string): string {
-  fs.mkdirSync(sessionDir, { recursive: true });
-
-  const sessionId = randomUUID();
-  const timestamp = new Date().toISOString();
-  const fileTimestamp = timestamp.replace(/[:.]/g, "-");
-  const sessionFile = path.join(sessionDir, `${fileTimestamp}_${sessionId}.jsonl`);
-  const header: SessionHeader = {
-    type: "session",
-    version: CURRENT_SESSION_VERSION,
-    id: sessionId,
-    timestamp,
-    cwd,
-  };
-
-  fs.writeFileSync(sessionFile, `${JSON.stringify(header)}\n`);
+/** Write a standalone handoff snapshot when Pi defers persistence; discard the manager afterward. */
+function persistFork(manager: SessionManager): string {
+  const sessionFile = manager.getSessionFile();
+  const header = manager.getHeader();
+  if (!sessionFile || !header) throw new Error("Failed to create branched session");
+  if (!fs.existsSync(sessionFile)) {
+    const contents =
+      [header, ...manager.getEntries()].map((entry) => JSON.stringify(entry)).join("\n") + "\n";
+    const fd = fs.openSync(sessionFile, "wx");
+    try {
+      fs.writeFileSync(fd, contents);
+    } catch (error) {
+      fs.rmSync(sessionFile, { force: true });
+      throw error;
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
   return sessionFile;
 }
 
 export default function (pi: ExtensionAPI) {
+  const launchObservers = new Set<() => void>();
+  pi.on("session_start", releaseLaunchObservers);
+  pi.on("session_shutdown", releaseLaunchObservers);
+
   pi.registerEntryRenderer<CommandMessageDetails>(BRANCH_ENTRY_TYPE, (entry, _options, theme) => {
     const details = entry.data;
     if (!details || typeof details.intro !== "string" || typeof details.command !== "string") {
@@ -287,7 +236,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerFlag(TERMINAL_FLAG, {
     description:
-      "Command to open a new terminal. Use {cwd} for working directory and optional {command} for the pi command.",
+      "Bash launcher template. Unquoted {cwd}, {session}, and {command} become single arguments; {command} is a command string for e.g. bash -c.",
     type: "string",
   });
 
@@ -320,44 +269,48 @@ export default function (pi: ExtensionAPI) {
       }
 
       const leafId = ctx.sessionManager.getLeafId();
-      const hasAssistantReply = ctx.sessionManager
+      const hasPersistedMessage = ctx.sessionManager
         .getEntries()
-        .some((entry) => entry.type === "message" && entry.message.role === "assistant");
+        .some(
+          (entry) =>
+            entry.type === "message" &&
+            (entry.message.role === "user" || entry.message.role === "assistant"),
+        );
 
       let forkFile: string;
       if (leafId && hasValidSessionFile(sessionFile)) {
-        const forkManager = SessionManager.open(sessionFile);
-        const branchedSessionFile = forkManager.createBranchedSession(leafId);
-        if (!branchedSessionFile) {
+        const forkManager = SessionManager.open(
+          sessionFile,
+          ctx.sessionManager.getSessionDir(),
+          ctx.cwd,
+        );
+        if (!forkManager.createBranchedSession(leafId)) {
           throw new Error("Failed to create branched session");
         }
-        forkFile = branchedSessionFile;
+        forkFile = persistFork(forkManager);
       } else {
-        if (hasAssistantReply) {
+        if (leafId && hasPersistedMessage) {
           throw new Error(`Current session file is missing or invalid: ${sessionFile}`);
         }
 
-        const message = "Current session has no persisted history yet. Opening a fresh session.";
+        const message = leafId
+          ? "Current session has no persisted history yet. Opening a fresh session."
+          : "Selected conversation is empty. Opening a fresh session.";
         if (ctx.hasUI) ctx.ui.notify(message, "warning");
-        else console.log(message);
+        else console.error(message);
 
-        forkFile = createFreshSessionFile(ctx.cwd, ctx.sessionManager.getSessionDir());
+        forkFile = persistFork(
+          SessionManager.create(ctx.cwd, ctx.sessionManager.getSessionDir(), {
+            parentSession: sessionFile,
+          }),
+        );
       }
 
-      const resumeCommand = `cd ${shellQuoteCompact(ctx.cwd)} && pi --session ${formatResumeSessionArgument(forkFile)}`;
+      const resumeCommand = `cd ${shellQuote(ctx.cwd)} && pi --session ${shellQuote(forkFile)}`;
 
       const terminalFlag = getStringFlag(pi, TERMINAL_FLAG);
       if (terminalFlag) {
-        const command = renderTerminalCommand(terminalFlag, ctx.cwd, forkFile);
-        spawnDetached("bash", ["-lc", command], (error) => {
-          if (ctx.hasUI) {
-            ctx.ui.notify(`Terminal command failed: ${error.message}`, "error");
-          } else {
-            console.error(`Terminal command failed: ${error.message}`);
-          }
-          showCommandMessage(pi, ctx, MANUAL_RESUME_INTRO, resumeCommand);
-        });
-        if (ctx.hasUI) ctx.ui.notify("Opened fork in new terminal", "info");
+        launchTerminal(terminalFlag, forkFile, resumeCommand, ctx);
         return;
       }
 
@@ -397,4 +350,64 @@ export default function (pi: ExtensionAPI) {
       showCommandMessage(pi, ctx, MANUAL_RESUME_INTRO, resumeCommand);
     },
   });
+
+  function launchTerminal(
+    template: string,
+    forkFile: string,
+    resumeCommand: string,
+    ctx: ExtensionCommandContext,
+  ) {
+    const reportFailure = (message: string) => {
+      try {
+        if (ctx.hasUI) ctx.ui.notify(`Terminal command failed: ${message}`, "error");
+        else console.error(`Terminal command failed: ${message}`);
+        showCommandMessage(pi, ctx, MANUAL_RESUME_INTRO, resumeCommand);
+      } catch (error) {
+        console.error(
+          `Could not show terminal recovery instructions: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        console.error(`${MANUAL_RESUME_INTRO}:\n${resumeCommand}`);
+      }
+    };
+    try {
+      const child = spawn("bash", ["-c", renderTerminalCommand(template)], {
+        cwd: ctx.cwd,
+        env: {
+          ...process.env,
+          TAU_BRANCH_CWD: ctx.cwd,
+          TAU_BRANCH_SESSION: forkFile,
+          TAU_BRANCH_COMMAND: `pi --session ${shellQuote(forkFile)}`,
+        },
+        detached: true,
+        stdio: "ignore",
+      });
+      const stopObserving = () => {
+        child.removeListener("error", onError);
+        child.removeListener("close", onClose);
+        launchObservers.delete(stopObserving);
+      };
+      const onError = (error: Error) => {
+        stopObserving();
+        reportFailure(error.message);
+      };
+      const onClose = (code: number | null, signal: NodeJS.Signals | null) => {
+        stopObserving();
+        if (code !== 0) reportFailure(signal ? `terminated by ${signal}` : `exit code ${code}`);
+      };
+      // A detached, user-owned launcher may still emit an error after Pi stops observing it.
+      child.on("error", ignoreDetachedLauncherError);
+      child.once("error", onError);
+      child.once("close", onClose);
+      launchObservers.add(stopObserving);
+      child.unref();
+    } catch (error) {
+      reportFailure(error instanceof Error ? error.message : String(error));
+      return;
+    }
+    if (ctx.hasUI) ctx.ui.notify("Terminal launch requested", "info");
+  }
+
+  function releaseLaunchObservers() {
+    for (const stopObserving of launchObservers) stopObserving();
+  }
 }

package/extensions/btw.ts

@@ -24,6 +24,7 @@ import {
   matchesKey,
   truncateToWidth,
   type Component,
+  type KeybindingsManager,
   type TUI,
   visibleWidth,
   wrapTextWithAnsi,
@@ -31,6 +32,9 @@ import {
 
 const STATUS_KEY = "0-btw";
 const RESULT_MARKDOWN_THEME = getMarkdownTheme();
+const MIN_RESULT_WIDTH = 50;
+const RESULT_CHROME_ROWS = 6;
+const MIN_RESULT_ROWS = RESULT_CHROME_ROWS + 3; // Two overlay margins and one reading row.
 const STATUS_SPINNER_INTERVAL_MS = 80;
 const STATUS_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
@@ -349,9 +353,11 @@ function seedSessionManager(sessionManager: SessionManager, messages: AgentMessa
 }
 
 async function showResultDialog(ctx: ExtensionContext, result: BtwResult): Promise<void> {
-  await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
-    return new BtwResultComponent(result, tui, theme, done);
-  });
+  await ctx.ui.custom<void>(
+    (tui, theme, keybindings, done) =>
+      new BtwResultComponent(result, tui, theme, keybindings, done),
+    { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", margin: 1 } },
+  );
 }
 
 function getLastAssistantMessage(messages: AgentMessage[]): AssistantMessage | null {
@@ -380,6 +386,7 @@ function extractText(content: AssistantMessage["content"]): string {
 class BtwResultComponent implements Component {
   private readonly markdown: Markdown;
   private scrollOffset = 0;
+  private renderWidth?: number;
   private cachedBodyWidth?: number;
   private cachedBodyLines?: string[];
 
@@ -387,6 +394,7 @@ class BtwResultComponent implements Component {
     private readonly result: BtwResult,
     private readonly tui: TUI,
     private readonly theme: Theme,
+    private readonly keybindings: KeybindingsManager,
     private readonly onDone: () => void,
   ) {
     this.markdown = new Markdown(result.answer, 0, 0, RESULT_MARKDOWN_THEME);
@@ -409,37 +417,62 @@ class BtwResultComponent implements Component {
       return;
     }
 
+    const width = this.renderWidth ?? this.tui.terminal.columns;
+    if (width < MIN_RESULT_WIDTH || this.tui.terminal.rows < MIN_RESULT_ROWS) return;
+
     const bodyHeight = this.getBodyHeight();
-    const boxWidth = this.getBoxWidth(this.tui.terminal.columns);
+    const boxWidth = width;
     const bodyLines = this.getBodyLines(this.getContentWidth(boxWidth));
     const maxScroll = Math.max(0, bodyLines.length - bodyHeight);
 
-    if (matchesKey(data, Key.up) || data.toLowerCase() === "k") {
-      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
-    } else if (matchesKey(data, Key.down) || data.toLowerCase() === "j") {
-      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
-    } else if (matchesKey(data, Key.pageUp)) {
-      this.scrollOffset = Math.max(0, this.scrollOffset - Math.max(4, bodyHeight - 2));
-    } else if (matchesKey(data, Key.pageDown)) {
-      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + Math.max(4, bodyHeight - 2));
-    } else if (matchesKey(data, Key.home)) {
+    this.scrollOffset = clamp(this.scrollOffset, 0, maxScroll);
+    const kb = this.keybindings;
+    if (kb.matches(data, "tui.altScreen.pageUp")) {
+      this.scrollOffset -= bodyHeight;
+    } else if (kb.matches(data, "tui.altScreen.pageDown")) {
+      this.scrollOffset += bodyHeight;
+    } else if (kb.matches(data, "tui.altScreen.halfPageUp")) {
+      this.scrollOffset -= Math.max(1, Math.floor(bodyHeight / 2));
+    } else if (kb.matches(data, "tui.altScreen.halfPageDown")) {
+      this.scrollOffset += Math.max(1, Math.floor(bodyHeight / 2));
+    } else if (kb.matches(data, "tui.altScreen.top")) {
       this.scrollOffset = 0;
-    } else if (matchesKey(data, Key.end)) {
+    } else if (kb.matches(data, "tui.altScreen.bottom")) {
       this.scrollOffset = maxScroll;
+    } else if (kb.matches(data, "tui.altScreen.lineUp")) {
+      this.scrollOffset -= 1;
+    } else if (kb.matches(data, "tui.altScreen.lineDown")) {
+      this.scrollOffset += 1;
+    } else if (matchesKey(data, Key.up) || data.toLowerCase() === "k") {
+      this.scrollOffset -= 1;
+    } else if (matchesKey(data, Key.down) || data.toLowerCase() === "j") {
+      this.scrollOffset += 1;
     } else {
       return;
     }
 
+    this.scrollOffset = clamp(this.scrollOffset, 0, maxScroll);
     this.tui.requestRender();
   }
 
   render(width: number): string[] {
-    const boxWidth = this.getBoxWidth(width);
+    this.renderWidth = width;
+    if (width < 1 || this.tui.terminal.rows <= 2) return [];
+    if (width < MIN_RESULT_WIDTH || this.tui.terminal.rows < MIN_RESULT_ROWS) {
+      return [
+        truncateToWidth(
+          this.theme.fg(
+            "muted",
+            `Esc close · Resize to ${MIN_RESULT_WIDTH + 2}+ columns, ${MIN_RESULT_ROWS}+ rows.`,
+          ),
+          width,
+          "",
+        ),
+      ];
+    }
+
+    const boxWidth = width;
     const contentWidth = this.getContentWidth(boxWidth);
-    const questionLines = wrapTextWithAnsi(
-      this.theme.fg("muted", this.result.question),
-      contentWidth,
-    );
     const bodyLines = this.getBodyLines(contentWidth);
     const bodyHeight = this.getBodyHeight();
     const maxScroll = Math.max(0, bodyLines.length - bodyHeight);
@@ -447,11 +480,7 @@ class BtwResultComponent implements Component {
 
     const lines: string[] = [];
     lines.push(this.borderLine("╭", "╮", boxWidth));
-    lines.push(this.boxLine(this.theme.bold("Request"), boxWidth));
-    for (const line of questionLines) {
-      lines.push(this.boxLine(line, boxWidth));
-    }
-    lines.push(this.separatorLine(boxWidth));
+    lines.push(this.boxLine(this.theme.bold("BTW"), boxWidth));
 
     const visibleBody = bodyLines.slice(this.scrollOffset, this.scrollOffset + bodyHeight);
     for (const line of visibleBody) {
@@ -463,15 +492,30 @@ class BtwResultComponent implements Component {
 
     lines.push(this.separatorLine(boxWidth));
     const scrollText = `${Math.min(bodyLines.length, this.scrollOffset + 1)}-${Math.min(bodyLines.length, this.scrollOffset + visibleBody.length)}/${bodyLines.length}`;
-    const controls = `${this.theme.fg("dim", "↑↓ scroll · PgUp/PgDn jump · Home/End · Enter/Esc close")} ${this.theme.fg("muted", scrollText)}`;
-    lines.push(this.boxLine(truncateToWidth(controls, contentWidth), boxWidth));
+    const navigation = [
+      ["pageUp", "pageDown", "page"],
+      ["top", "bottom", "ends"],
+    ] as const;
+    const hints = [
+      "↑↓/j/k scroll",
+      ...navigation.flatMap(([up, down, label]) => {
+        const keys = [up, down].map((action) =>
+          this.keybindings
+            .getKeys(`tui.altScreen.${action}`)
+            .find((key) => !["enter", "escape", "ctrl+c", "q"].includes(key)),
+        );
+        return keys.some(Boolean) ? [`${keys.map((key) => key ?? "—").join("/")} ${label}`] : [];
+      }),
+    ];
+    lines.push(this.boxLine(this.theme.fg("dim", hints.join(" · ")), boxWidth));
+    lines.push(this.boxLine(this.theme.fg("dim", `Enter/Esc close · ${scrollText}`), boxWidth));
     lines.push(this.borderLine("╰", "╯", boxWidth));
 
     return lines;
   }
 
   private getBodyHeight(): number {
-    return Math.max(8, this.tui.terminal.rows - 14);
+    return this.tui.terminal.rows - 2 - RESULT_CHROME_ROWS;
   }
 
   private getBodyLines(contentWidth: number): string[] {
@@ -479,18 +523,20 @@ class BtwResultComponent implements Component {
       return this.cachedBodyLines;
     }
 
-    const lines = this.markdown.render(contentWidth);
+    const lines = [
+      this.theme.bold("Request"),
+      ...wrapTextWithAnsi(this.theme.fg("muted", this.result.question), contentWidth),
+      "",
+      this.theme.bold("Answer"),
+      ...this.markdown.render(contentWidth),
+    ];
     this.cachedBodyWidth = contentWidth;
     this.cachedBodyLines = lines;
     return lines;
   }
 
-  private getBoxWidth(width: number): number {
-    return Math.max(50, Math.min(width - 2, 140));
-  }
-
   private getContentWidth(boxWidth: number): number {
-    return Math.max(10, boxWidth - 4);
+    return boxWidth - 4;
   }
 
   private borderLine(left: string, right: string, width: number): string {

package/extensions/caffeinate/README.md

@@ -0,0 +1,5 @@
+# Caffeinate
+
+`caffeinate` prevents system sleep during agent runs, including retries, automatic compaction, and queued follow-ups. It releases the inhibitor when the agent settles or the session closes or reloads. Display sleep settings remain unchanged.
+
+macOS uses `caffeinate -i`; Linux uses `systemd-inhibit --what=sleep` and requires an accessible, authorized logind service. Linux's sleep lock can also block manual suspend; lid-close and forced-sleep behavior remain OS-policy decisions. If inhibition is unavailable, Pi warns once per load, on the first failed attempt, and continues normally. There are no commands or settings; disable the extension through Pi's package configuration if unwanted.

package/extensions/caffeinate/index.ts

@@ -0,0 +1,144 @@
+/** Keep the system awake during agent runs without inhibiting display sleep. */
+
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import { stripVTControlCharacters } from "node:util";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+interface InhibitCommand {
+  command: string;
+  args: string[];
+  waitForStdin: boolean;
+}
+
+export default function (pi: ExtensionAPI) {
+  let inhibitor: ReturnType<typeof startInhibitor> | undefined;
+  let releasing = Promise.resolve();
+  let shutdown = false;
+  let warned = false;
+
+  pi.on("agent_start", async (_event, ctx) => {
+    await releasing;
+    if (shutdown || inhibitor) return;
+    const command = inhibitCommand();
+    if (!command) return;
+    try {
+      inhibitor = startInhibitor(command, ctx.cwd, (reason) => warn(ctx, reason));
+    } catch (error) {
+      warn(ctx, error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (!shutdown && ctx.isIdle()) await release();
+  });
+
+  pi.on("session_shutdown", async () => {
+    shutdown = true;
+    await release();
+  });
+
+  async function release() {
+    if (inhibitor) {
+      releasing = inhibitor.stop();
+      inhibitor = undefined;
+    }
+    await releasing;
+  }
+
+  function warn(ctx: ExtensionContext, reason: string) {
+    if (shutdown || warned) return;
+    warned = true;
+    const message = `Caffeinate: sleep prevention unavailable. ${stripVTControlCharacters(reason)}`;
+    try {
+      if (ctx.hasUI) {
+        ctx.ui.notify(message, "warning");
+        return;
+      }
+    } catch {
+      // A missing UI must not turn an optional inhibitor failure into an uncaught error.
+    }
+    console.warn(message);
+  }
+}
+
+function inhibitCommand(): InhibitCommand | undefined {
+  switch (platform()) {
+    case "darwin":
+      return {
+        command: "/usr/bin/caffeinate",
+        args: ["-i", "-w", String(process.pid)],
+        waitForStdin: false,
+      };
+    case "linux":
+      return {
+        command: "systemd-inhibit",
+        args: [
+          "--what=sleep",
+          "--mode=block",
+          "--who=Pi",
+          "--why=Pi agent is running",
+          "--",
+          "cat",
+        ],
+        waitForStdin: true,
+      };
+  }
+}
+
+/** Own the inhibitor through close; a parent PID watch or stdin EOF also releases it if Pi exits. */
+function startInhibitor(command: InhibitCommand, cwd: string, onFailure: (reason: string) => void) {
+  const child = spawn(command.command, command.args, {
+    cwd,
+    detached: true,
+    stdio: ["pipe", "ignore", "pipe"],
+  });
+  let stderr = "";
+  let error: string | undefined;
+  let stopped = false;
+  let closed = false;
+  let escalation: NodeJS.Timeout | undefined;
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk: string) => {
+    stderr = (stderr + chunk).slice(0, 2048);
+  });
+  child.on("error", (cause: Error) => {
+    error = cause.message;
+  });
+  child.stdin.on("error", (cause: Error) => {
+    error = cause.message;
+  });
+  const completion = new Promise<void>((resolve) => {
+    child.once("close", (code, signal) => {
+      closed = true;
+      clearTimeout(escalation);
+      if (!stopped) {
+        onFailure(
+          error || stderr.trim() || `${command.command} exited unexpectedly (${signal ?? code}).`,
+        );
+      }
+      resolve();
+    });
+  });
+
+  return {
+    stop() {
+      if (!stopped && !closed) {
+        stopped = true;
+        child.stdin.end();
+        if (!command.waitForStdin) sendSignal("SIGTERM");
+        escalation = setTimeout(() => sendSignal("SIGKILL"), 500);
+      }
+      return completion;
+    },
+  };
+
+  function sendSignal(signal: "SIGTERM" | "SIGKILL") {
+    if (closed || child.pid === undefined) return;
+    try {
+      process.kill(-child.pid, signal);
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "ESRCH") child.kill(signal);
+    }
+  }
+}