aiwcli 0.15.2 → 0.15.4

package/dist/commands/launch.d.ts

@@ -22,6 +22,7 @@ export default class LaunchCommand extends BaseCommand {
     run(): Promise<void>;
     private buildTmuxShellCommand;
     private isTmuxAvailable;
+    private isWindowsTerminalAvailable;
     private sanitizeTmuxSessionName;
     private buildUniqueTmuxSessionName;
     private enableTmuxMouseIfPossible;

package/dist/commands/launch.js

@@ -26,7 +26,7 @@ export default class LaunchCommand extends BaseCommand {
         '  0  Success - AI assistant launched and exited successfully\n' +
         '  1  General error - unexpected runtime failure\n' +
         '  2  Invalid usage - check your arguments and flags\n' +
-        '  3  Environment error - CLI/tmux not found (install Claude Code from https://claude.ai/download, Codex from npm, tmux from your package manager)';
+        '  3  Environment error - CLI not found (install Claude Code from https://claude.ai/download, Codex from npm)';
     static examples = [
         '<%= config.bin %> <%= command.id %>  # Auto-launches tmux with a fresh session when not already in tmux',
         '<%= config.bin %> <%= command.id %> --codex  # Launch Codex with --yolo flag',
@@ -112,11 +112,7 @@ export default class LaunchCommand extends BaseCommand {
             // Spawn AI CLI with sandbox permissions disabled
             // AIW hook system provides safety guardrails
             // Continue launch regardless of version check result (graceful degradation)
-            if (shouldAutoTmux) {
-                if (!this.isTmuxAvailable()) {
-                    this.error('tmux is required for default launch mode but was not found on PATH.\n' +
-                        'Install tmux, or rerun with --no-tmux to launch directly.', { exit: EXIT_CODES.ENVIRONMENT_ERROR });
-                }
+            if (shouldAutoTmux && this.isTmuxAvailable()) {
                 const shellCommand = this.buildTmuxShellCommand(cliCommand, cliArgs);
                 const sessionFromFlag = flags['tmux-session']?.trim();
                 if (sessionFromFlag && sessionFromFlag.length > 0) {
@@ -131,15 +127,24 @@ export default class LaunchCommand extends BaseCommand {
                     exitCode = await spawnProcess('tmux', ['new-session', '-s', sessionName, shellCommand]);
                 }
             }
+            else if (shouldAutoTmux && this.isWindowsTerminalAvailable()) {
+                this.logInfo('tmux unavailable; launching in Windows Terminal split pane');
+                exitCode = await spawnProcess('wt', ['split-pane', '--', cliCommand, ...cliArgs]);
+            }
             else {
-                if (disableTmux)
+                if (shouldAutoTmux) {
+                    this.logInfo('No pane launcher available. Launching directly.');
+                }
+                else if (disableTmux) {
                     this.debug('tmux launch disabled via --no-tmux');
+                }
                 else if (insideTmux) {
                     this.debug('Already inside tmux; launching directly in current pane');
                     this.enableTmuxMouseIfPossible();
                 }
-                else if (!interactiveTty)
+                else if (!interactiveTty) {
                     this.debug('Non-interactive terminal detected; launching directly');
+                }
                 exitCode = await spawnProcess(cliCommand, cliArgs);
             }
         }
@@ -168,6 +173,17 @@ export default class LaunchCommand extends BaseCommand {
             return false;
         }
     }
+    isWindowsTerminalAvailable() {
+        if (process.platform !== 'win32')
+            return false;
+        try {
+            execSync('where wt', { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     sanitizeTmuxSessionName(input) {
         const trimmed = input.trim().toLowerCase();
         const safe = trimmed

package/dist/templates/_shared/lib-ts/agent-exec/backends/tmux.ts

@@ -8,17 +8,20 @@
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 
 import { execFileAsync } from "../../base/subprocess-utils.js";
+import {
+  buildShellCaptureScript,
+  cleanupSentinelIpc,
+  createSentinelIpcPaths,
+  readSentinelExitCode,
+  readTextIfExists,
+  waitForSentinelFile,
+} from "../../base/sentinel-ipc.js";
 import { getTmuxAvailability, quoteForSh, normalizeSplitFlag } from "../../base/tmux-driver.js";
 import type { ExecutionBackend, ExecutionRequest, ExecutionResult } from "../execution-backend.js";
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 export interface TmuxBackendOptions {
   splitFlag?: string;
   splitTarget?: string;
@@ -32,7 +35,7 @@ export class TmuxBackend implements ExecutionBackend {
   }
 
   async execute(request: ExecutionRequest): Promise<ExecutionResult> {
-    const tmux = getTmuxAvailability();
+    const tmux = getTmuxAvailability({ requireSessionEnv: true });
     if (!tmux.available || !tmux.tmuxPath) {
       return {
         stdout: "",
@@ -43,38 +46,23 @@ export class TmuxBackend implements ExecutionBackend {
       };
     }
 
-    // Create temp directory for IPC files
     const agentName = path.basename(request.cliPath).replace(/\.[^.]+$/, "");
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `aiwcli-agent-${agentName}-`));
-
-    const promptPath = path.join(tmpDir, "prompt.txt");
-    const stdoutPath = path.join(tmpDir, "stdout.txt");
-    const stderrPath = path.join(tmpDir, "stderr.txt");
-    const sentinelPath = path.join(tmpDir, "sentinel.txt");
+    const ipc = createSentinelIpcPaths(`aiwcli-agent-${agentName}`);
 
     try {
-      // Write prompt to file for stdin redirection
-      fs.writeFileSync(promptPath, request.input, "utf-8");
+      fs.writeFileSync(ipc.inputPath, request.input, "utf-8");
 
-      // Build env prefix
       const envEntries = Object.entries(request.env).filter(
-        ([, v]) => v !== undefined,
+        ([, value]) => value !== undefined,
       ) as Array<[string, string]>;
       const envPrefix = envEntries
-        .map(([k, v]) => `${k}=${quoteForSh(v)}`)
+        .map(([key, value]) => `${key}=${quoteForSh(value)}`)
         .join(" ");
 
-      // Build command
-      const quotedArgs = request.args.map((a) => quoteForSh(a)).join(" ");
-      const script = [
-        `${envPrefix} ${quoteForSh(request.cliPath)} ${quotedArgs}`,
-        `< ${quoteForSh(promptPath)}`,
-        `> ${quoteForSh(stdoutPath)}`,
-        `2> ${quoteForSh(stderrPath)}`,
-        `; echo $? > ${quoteForSh(sentinelPath)}`,
-      ].join(" ");
-
-      // Launch tmux pane
+      const quotedArgs = request.args.map((arg) => quoteForSh(arg)).join(" ");
+      const command = `${envPrefix} ${quoteForSh(request.cliPath)} ${quotedArgs}`.trim();
+      const script = buildShellCaptureScript(command, ipc, quoteForSh);
+
       const splitFlag = normalizeSplitFlag(this.options.splitFlag);
       const tmuxArgs = ["split-window", splitFlag, "-P", "-F", "#{pane_id}"];
       if (this.options.splitTarget) {
@@ -94,16 +82,9 @@ export class TmuxBackend implements ExecutionBackend {
       }
 
       const paneId = split.stdout.trim().split(/\r?\n/).pop() ?? "";
+      const finished = await waitForSentinelFile(ipc.sentinelPath, request.timeoutMs);
 
-      // Poll for sentinel file
-      const deadline = Date.now() + request.timeoutMs;
-      while (Date.now() < deadline) {
-        if (fs.existsSync(sentinelPath)) break;
-        await sleep(250);
-      }
-
-      if (!fs.existsSync(sentinelPath)) {
-        // Timeout: kill pane
+      if (!finished) {
         if (paneId) {
           await execFileAsync(tmux.tmuxPath, ["kill-pane", "-t", paneId], { timeout: 3000 });
         }
@@ -116,12 +97,10 @@ export class TmuxBackend implements ExecutionBackend {
         };
       }
 
-      // Read results
-      const exitCode = parseInt(fs.readFileSync(sentinelPath, "utf-8").trim(), 10) || 1;
-      const stdout = fs.existsSync(stdoutPath) ? fs.readFileSync(stdoutPath, "utf-8") : "";
-      const stderr = fs.existsSync(stderrPath) ? fs.readFileSync(stderrPath, "utf-8") : "";
+      const exitCode = readSentinelExitCode(ipc.sentinelPath, 1);
+      const stdout = readTextIfExists(ipc.stdoutPath);
+      const stderr = readTextIfExists(ipc.stderrPath);
 
-      // If outputFilePath specified and exists, read from it instead
       if (request.outputFilePath && fs.existsSync(request.outputFilePath)) {
         return {
           stdout: fs.readFileSync(request.outputFilePath, "utf-8"),
@@ -134,12 +113,7 @@ export class TmuxBackend implements ExecutionBackend {
 
       return { stdout, stderr, exitCode, killed: false, signal: null };
     } finally {
-      // Clean up temp dir
-      try {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
-      } catch {
-        // Best-effort cleanup
-      }
+      cleanupSentinelIpc(ipc);
     }
   }
 }

package/dist/templates/_shared/lib-ts/base/launchers/tmux-launcher.ts

@@ -0,0 +1,173 @@
+import { execFileAsync, findExecutable } from "../subprocess-utils.js";
+import { findBestSplit, listPanes } from "../tmux-pane-placement.js";
+import type { PaneLaunchOptions, PaneLaunchResult, PaneLauncher } from "../pane-launcher.js";
+
+export type TmuxSplitFlag = "-h" | "-v";
+
+export interface TmuxAvailability {
+  available: boolean;
+  tmuxPath?: string;
+  reason?: string;
+}
+
+export interface TmuxLauncherOptions {
+  requireSessionEnv?: boolean;
+}
+
+export function quoteForSh(input: string): string {
+  return `'${input.replaceAll("'", "'\"'\"'")}'`;
+}
+
+export function normalizeSplitFlag(value: string | undefined): TmuxSplitFlag {
+  return value?.trim() === "-v" ? "-v" : "-h";
+}
+
+export function getTmuxAvailability(options?: TmuxLauncherOptions): TmuxAvailability {
+  const requireSessionEnv = options?.requireSessionEnv ?? true;
+  if (requireSessionEnv && !process.env.TMUX) {
+    return { available: false, reason: "TMUX is not set" };
+  }
+
+  const tmuxPath = findExecutable("tmux");
+  if (!tmuxPath) {
+    return { available: false, reason: "tmux not found on PATH" };
+  }
+
+  return { available: true, tmuxPath };
+}
+
+function splitFlagFromDimensions(width: number, height: number): TmuxSplitFlag {
+  // Terminal cells are ~2x taller than wide. Correct for aspect ratio so BSP
+  // splits the visually longer axis, not just the higher character count.
+  const CELL_ASPECT_RATIO = 2.0;
+  return width >= height * CELL_ASPECT_RATIO ? "-h" : "-v";
+}
+
+function getLastLine(text: string): string {
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  return lines.at(-1) ?? "";
+}
+
+async function resolveSplitFlagForTargetPane(
+  tmuxPath: string,
+  splitTarget: string,
+): Promise<TmuxSplitFlag | null> {
+  const size = await execFileAsync(
+    tmuxPath,
+    ["display-message", "-p", "-t", splitTarget, "#{pane_width} #{pane_height}"],
+    { timeout: 3000 },
+  );
+  if (size.exitCode !== 0) return null;
+
+  const parts = size.stdout.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+
+  const width = Number.parseInt(parts[0] ?? "", 10);
+  const height = Number.parseInt(parts[1] ?? "", 10);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+
+  return splitFlagFromDimensions(width, height);
+}
+
+async function resolveAutoSplit(
+  tmuxPath: string,
+  splitTarget?: string,
+): Promise<{ splitFlag: TmuxSplitFlag; splitTarget?: string }> {
+  const explicitTarget = splitTarget?.trim();
+  if (explicitTarget) {
+    const splitFlag = await resolveSplitFlagForTargetPane(tmuxPath, explicitTarget);
+    return {
+      splitFlag: splitFlag ?? "-h",
+      splitTarget: explicitTarget,
+    };
+  }
+
+  const panes = await listPanes(tmuxPath);
+  const placement = findBestSplit(panes);
+  if (!placement) return { splitFlag: "-h" };
+
+  return {
+    splitFlag: placement.splitFlag,
+    splitTarget: placement.targetPane,
+  };
+}
+
+export class TmuxLauncher implements PaneLauncher {
+  readonly backend = "tmux" as const;
+  private options: TmuxLauncherOptions;
+
+  constructor(options?: TmuxLauncherOptions) {
+    this.options = options ?? {};
+  }
+
+  async available(): Promise<boolean> {
+    return getTmuxAvailability(this.options).available;
+  }
+
+  async launch(options: PaneLaunchOptions): Promise<PaneLaunchResult> {
+    const tmux = getTmuxAvailability(this.options);
+    if (!tmux.available || !tmux.tmuxPath) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: tmux.reason ?? "tmux unavailable",
+      };
+    }
+
+    const splitDirection = options.splitDirection ?? "h";
+    const explicitTarget = options.splitTarget?.trim();
+
+    let splitFlag: TmuxSplitFlag;
+    let splitTarget: string | undefined;
+
+    if (splitDirection === "auto") {
+      try {
+        const resolved = await resolveAutoSplit(tmux.tmuxPath, explicitTarget);
+        splitFlag = resolved.splitFlag;
+        splitTarget = resolved.splitTarget;
+      } catch {
+        splitFlag = "-h";
+        splitTarget = explicitTarget;
+      }
+    } else {
+      splitFlag = splitDirection === "v" ? "-v" : "-h";
+      splitTarget = explicitTarget;
+    }
+
+    const body = options.cwd?.trim()
+      ? `cd ${quoteForSh(options.cwd.trim())} && ${options.command}`
+      : options.command;
+
+    const tmuxArgs = ["split-window", splitFlag, "-P", "-F", "#{pane_id}"];
+    if (splitTarget) tmuxArgs.push("-t", splitTarget);
+    tmuxArgs.push(`bash -lc ${quoteForSh(body)}`);
+
+    const split = await execFileAsync(tmux.tmuxPath, tmuxArgs, { timeout: 5000 });
+    if (split.exitCode !== 0) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "tmux split-window failed",
+        stderr: split.stderr.trim() || undefined,
+      };
+    }
+
+    const paneId = getLastLine(split.stdout) || undefined;
+    return {
+      launched: true,
+      backend: this.backend,
+      paneId,
+    };
+  }
+
+  async kill(paneId: string): Promise<void> {
+    if (!paneId) return;
+
+    const tmux = getTmuxAvailability(this.options);
+    if (!tmux.available || !tmux.tmuxPath) return;
+
+    await execFileAsync(tmux.tmuxPath, ["kill-pane", "-t", paneId], {
+      timeout: 3000,
+    });
+  }
+}

package/dist/templates/_shared/lib-ts/base/launchers/window-launcher.ts

@@ -0,0 +1,93 @@
+import { execFileAsync, findExecutable } from "../subprocess-utils.js";
+import { quoteForSh } from "./tmux-launcher.js";
+import type { PaneLaunchOptions, PaneLaunchResult, PaneLauncher } from "../pane-launcher.js";
+
+function quoteForPowerShell(input: string): string {
+  return `'${input.replaceAll("'", "''")}'`;
+}
+
+function findPowerShell(): string | null {
+  return findExecutable("pwsh") ?? findExecutable("powershell");
+}
+
+export class WindowLauncher implements PaneLauncher {
+  readonly backend = "window" as const;
+
+  async available(): Promise<boolean> {
+    if (process.platform !== "win32") return false;
+    return Boolean(findPowerShell() ?? findExecutable("mintty"));
+  }
+
+  async launch(options: PaneLaunchOptions): Promise<PaneLaunchResult> {
+    if (process.platform !== "win32") {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "window launcher only available on Windows",
+      };
+    }
+
+    const powershellPath = findPowerShell();
+    if (powershellPath) {
+      const cwd = options.cwd?.trim() || process.cwd();
+      const startProcess = [
+        `$cmd = ${quoteForPowerShell(options.command)}`,
+        `$wd = ${quoteForPowerShell(cwd)}`,
+        `Start-Process -FilePath ${quoteForPowerShell(powershellPath)} -WorkingDirectory $wd -ArgumentList @('-NoProfile','-Command',$cmd) | Out-Null`,
+      ].join("; ");
+
+      const psLaunch = await execFileAsync(
+        powershellPath,
+        ["-NoProfile", "-Command", startProcess],
+        { timeout: 5000, shell: false },
+      );
+
+      if (psLaunch.exitCode === 0) {
+        return {
+          launched: true,
+          backend: this.backend,
+        };
+      }
+
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "Start-Process launch failed",
+        stderr: psLaunch.stderr.trim() || undefined,
+      };
+    }
+
+    const minttyPath = findExecutable("mintty");
+    if (!minttyPath) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "PowerShell and mintty are both unavailable",
+      };
+    }
+
+    const shellBody = options.cwd?.trim()
+      ? `cd ${quoteForSh(options.cwd.trim())} && ${options.command}`
+      : options.command;
+
+    const minttyLaunch = await execFileAsync(
+      minttyPath,
+      ["-e", "bash", "-lc", shellBody],
+      { timeout: 5000, shell: false },
+    );
+
+    if (minttyLaunch.exitCode !== 0) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "mintty launch failed",
+        stderr: minttyLaunch.stderr.trim() || undefined,
+      };
+    }
+
+    return {
+      launched: true,
+      backend: this.backend,
+    };
+  }
+}

package/dist/templates/_shared/lib-ts/base/launchers/wt-launcher.ts

@@ -0,0 +1,64 @@
+import { execFileAsync, findExecutable } from "../subprocess-utils.js";
+import type { PaneLaunchOptions, PaneLaunchResult, PaneLauncher } from "../pane-launcher.js";
+
+function findPowerShell(): string {
+  return findExecutable("pwsh") ?? findExecutable("powershell") ?? "powershell";
+}
+
+export class WtLauncher implements PaneLauncher {
+  readonly backend = "wt" as const;
+
+  async available(): Promise<boolean> {
+    if (process.platform !== "win32") return false;
+    return Boolean(findExecutable("wt") ?? findExecutable("wt.exe"));
+  }
+
+  async launch(options: PaneLaunchOptions): Promise<PaneLaunchResult> {
+    if (process.platform !== "win32") {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "wt launcher only available on Windows",
+      };
+    }
+
+    const wtPath = findExecutable("wt") ?? findExecutable("wt.exe");
+    if (!wtPath) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "wt.exe not found on PATH",
+      };
+    }
+
+    const args = ["split-pane"];
+    const splitDirection = options.splitDirection ?? "auto";
+    if (splitDirection === "h") args.push("-H");
+    if (splitDirection === "v") args.push("-V");
+
+    if (options.cwd?.trim()) args.push("-d", options.cwd.trim());
+    if (options.title?.trim()) args.push("--title", options.title.trim());
+
+    const powershellPath = findPowerShell();
+    args.push("--", powershellPath, "-NoProfile", "-Command", options.command);
+
+    const result = await execFileAsync(wtPath, args, {
+      timeout: 5000,
+      shell: false,
+    });
+
+    if (result.exitCode !== 0) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "wt split-pane failed",
+        stderr: result.stderr.trim() || undefined,
+      };
+    }
+
+    return {
+      launched: true,
+      backend: this.backend,
+    };
+  }
+}

package/dist/templates/_shared/lib-ts/base/pane-launcher.ts

@@ -0,0 +1,55 @@
+import { TmuxLauncher } from "./launchers/tmux-launcher.js";
+import { WindowLauncher } from "./launchers/window-launcher.js";
+import { WtLauncher } from "./launchers/wt-launcher.js";
+
+export type PaneBackend = "tmux" | "wt" | "window" | "exec";
+export type PaneSplitDirection = "h" | "v" | "auto";
+
+export interface PaneLaunchOptions {
+  command: string;
+  splitDirection?: PaneSplitDirection;
+  splitTarget?: string;
+  cwd?: string;
+  title?: string;
+}
+
+export interface PaneLaunchResult {
+  launched: boolean;
+  backend: PaneBackend;
+  paneId?: string;
+  reason?: string;
+  stderr?: string;
+}
+
+export interface PaneLauncher {
+  readonly backend: PaneBackend;
+  available(): Promise<boolean>;
+  launch(options: PaneLaunchOptions): Promise<PaneLaunchResult>;
+  kill?(paneId: string): Promise<void>;
+}
+
+export interface PaneLauncherFactoryOptions {
+  /** Include tmux launcher only when running inside a tmux session. Default: true. */
+  requireTmuxSession?: boolean;
+}
+
+/**
+ * Resolve the first available pane launcher for the current environment.
+ * Detection order: tmux -> Windows Terminal -> window fallback.
+ */
+export async function createPaneLauncher(
+  options?: PaneLauncherFactoryOptions,
+): Promise<PaneLauncher | null> {
+  const requireTmuxSession = options?.requireTmuxSession ?? true;
+
+  const tmux = new TmuxLauncher({ requireSessionEnv: requireTmuxSession });
+  if (await tmux.available()) return tmux;
+
+  const wt = new WtLauncher();
+  if (await wt.available()) return wt;
+
+  const window = new WindowLauncher();
+  if (await window.available()) return window;
+
+  return null;
+}

package/dist/templates/_shared/lib-ts/base/sentinel-ipc.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface SentinelIpcPaths {
+  tmpDir: string;
+  inputPath: string;
+  stdoutPath: string;
+  stderrPath: string;
+  sentinelPath: string;
+}
+
+function sanitizePrefix(prefix: string): string {
+  return prefix.replaceAll(/[^a-zA-Z0-9_-]/g, "-");
+}
+
+export function createSentinelIpcPaths(prefix: string): SentinelIpcPaths {
+  const safePrefix = sanitizePrefix(prefix);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `${safePrefix}-`));
+
+  return {
+    tmpDir,
+    inputPath: path.join(tmpDir, "input.txt"),
+    stdoutPath: path.join(tmpDir, "stdout.txt"),
+    stderrPath: path.join(tmpDir, "stderr.txt"),
+    sentinelPath: path.join(tmpDir, "sentinel.txt"),
+  };
+}
+
+export function buildShellCaptureScript(
+  command: string,
+  paths: Pick<SentinelIpcPaths, "inputPath" | "stdoutPath" | "stderrPath" | "sentinelPath">,
+  quote: (input: string) => string,
+): string {
+  return [
+    command,
+    `< ${quote(paths.inputPath)}`,
+    `> ${quote(paths.stdoutPath)}`,
+    `2> ${quote(paths.stderrPath)}`,
+    `; echo $? > ${quote(paths.sentinelPath)}`,
+  ].join(" ");
+}
+
+export async function waitForSentinelFile(
+  sentinelPath: string,
+  timeoutMs: number,
+  pollIntervalMs = 250,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(sentinelPath)) return true;
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+
+  return fs.existsSync(sentinelPath);
+}
+
+export function readSentinelExitCode(sentinelPath: string, fallback = 1): number {
+  if (!fs.existsSync(sentinelPath)) return fallback;
+
+  const raw = fs.readFileSync(sentinelPath, "utf-8").trim();
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function readTextIfExists(filePath: string): string {
+  if (!filePath || !fs.existsSync(filePath)) return "";
+  return fs.readFileSync(filePath, "utf-8");
+}
+
+export function cleanupSentinelIpc(paths: Pick<SentinelIpcPaths, "tmpDir">): void {
+  try {
+    fs.rmSync(paths.tmpDir, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup.
+  }
+}
+
+export function cleanupSentinelPath(sentinelPath: string | undefined): void {
+  if (!sentinelPath) return;
+
+  try {
+    fs.rmSync(path.dirname(sentinelPath), { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup.
+  }
+}