aiwcli 0.15.5 → 0.15.7

package/dist/templates/core/lib-ts/runtime/executable-policy.ts

@@ -0,0 +1,89 @@
+import { execSync } from 'node:child_process'
+import type { ExecSyncOptionsWithStringEncoding } from 'node:child_process'
+
+import { commandLookupBinary, isWindowsPlatform } from './platform-adapter.js'
+
+export type WindowsLookupProfile = 'cmdOrExeFirst' | 'exeThenExtensionlessThenCmd'
+
+export function parseLookupLines(stdout: string): string[] {
+  return stdout
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+}
+
+export function pickWindowsPath(lines: string[], profile: WindowsLookupProfile): null | string {
+  if (lines.length === 0) return null
+
+  if (profile === 'cmdOrExeFirst') {
+    return lines.find((line) => /\.(cmd|exe)$/i.test(line)) ?? lines[0] ?? null
+  }
+
+  return lines.find((line) => /\.exe$/i.test(line))
+    ?? lines.find((line) => !/\.(cmd|ps1)$/i.test(line))
+    ?? lines.find((line) => /\.cmd$/i.test(line))
+    ?? lines[0]
+    ?? null
+}
+
+export function selectLookupPath(
+  lines: string[],
+  platform: NodeJS.Platform = process.platform,
+  windowsProfile: WindowsLookupProfile = 'cmdOrExeFirst',
+): null | string {
+  if (lines.length === 0) return null
+  if (!isWindowsPlatform(platform)) return lines[0] ?? null
+  return pickWindowsPath(lines, windowsProfile)
+}
+
+export function resolveExecutable(
+  name: string,
+  options?: {
+    platform?: NodeJS.Platform | undefined
+    timeoutMs?: number | undefined
+    windowsHide?: boolean | undefined
+    windowsProfile?: undefined | WindowsLookupProfile
+  },
+): null | string {
+  const platform = options?.platform ?? process.platform
+  const lines = lookupExecutables(name, {
+    platform,
+    timeoutMs: options?.timeoutMs,
+    windowsHide: options?.windowsHide,
+  })
+  return selectLookupPath(lines, platform, options?.windowsProfile ?? 'cmdOrExeFirst')
+}
+
+export function isCommandAvailable(
+  name: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  return resolveExecutable(name, { platform }) !== null
+}
+
+export function lookupExecutables(
+  name: string,
+  options?: {
+    platform?: NodeJS.Platform | undefined
+    timeoutMs?: number | undefined
+    windowsHide?: boolean | undefined
+  },
+): string[] {
+  const platform = options?.platform ?? process.platform
+  const lookupBin = commandLookupBinary(platform)
+  const cmd = `${lookupBin} ${name}`
+
+  try {
+    return parseLookupLines(execSync(cmd, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: true,
+      timeout: options?.timeoutMs ?? 3000,
+      windowsHide: options?.windowsHide ?? true,
+    } as unknown as ExecSyncOptionsWithStringEncoding))
+  } catch {
+    return []
+  }
+}
+

package/dist/templates/{_shared/lib-ts/base → core/lib-ts/runtime}/git-state.ts

@@ -4,13 +4,13 @@ import { execFileSync } from "node:child_process";
  * Capture current git state for session snapshots.
  * All fields are optional — failures are silently ignored.
  */
-export function getGitState(projectRoot: string): Record<string, any> {
-  const gitState: Record<string, any> = {};
+export function getGitState(projectRoot: string): Record<string, unknown> {
+  const gitState: Record<string, unknown> = {};
   const isWin = process.platform === "win32";
   const opts = {
     cwd: projectRoot,
     timeout: 5000,
-    encoding: "utf-8" as const,
+    encoding: "utf8" as const,
     stdio: ["pipe", "pipe", "pipe"] as ["pipe", "pipe", "pipe"],
     shell: isWin,
   };
@@ -45,7 +45,7 @@ export function getGitState(projectRoot: string): Record<string, any> {
 export function getGitStatusShort(projectRoot?: string): string {
   try {
     const result = execFileSync("git", ["status", "--short"], {
-      encoding: "utf-8",
+      encoding: "utf8",
       timeout: 5000,
       stdio: ["pipe", "pipe", "pipe"],
       ...(projectRoot ? { cwd: projectRoot } : {}),
@@ -56,3 +56,5 @@ export function getGitStatusShort(projectRoot?: string): string {
     return "(git status unavailable)";
   }
 }
+
+

package/dist/templates/{_shared/lib-ts/base → core/lib-ts/runtime}/inference.ts

@@ -9,7 +9,6 @@ import { execFileSync } from "node:child_process";
 import { logDebug, logWarn } from "./logger.js";
 import { STOP_WORDS } from "./stop-words.js";
 import type { InferenceResult } from "../types.js";
-import { execFileAsync } from "./subprocess-utils.js";
 import {
   buildCliInvocation,
   inferenceSpec,
@@ -19,6 +18,7 @@ import {
   TIER_TIMEOUTS,
 } from "./cli-args.js";
 import { CODEX_MODELS } from "./models.js";
+import { execFileAsync } from "./subprocess-utils.js";
 
 const CONTEXT_ID_PRIMARY_MODEL = CODEX_MODELS.spark;
 
@@ -35,7 +35,6 @@ export function inference(
 ): InferenceResult {
   const startTime = Date.now();
   const modelInput = options?.model ?? level;
-  const model = resolveModel(modelInput);
   const timeoutSec = timeout ?? (isModelTier(modelInput) ? getTierTimeout(modelInput) : TIER_TIMEOUTS.fast);
   const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
 
@@ -55,7 +54,7 @@ export function inference(
       {
         timeout: timeoutSec * 1000,
         env: invocation.env,
-        encoding: "utf-8",
+        encoding: "utf8",
         stdio: ["pipe", "pipe", "pipe"],
         shell: isWin,
       },
@@ -67,10 +66,17 @@ export function inference(
       output: stdout.trim(),
       latency_ms: latencyMs,
     };
-  } catch (error: any) {
+  } catch (error: unknown) {
     const latencyMs = Date.now() - startTime;
+    const execError = error as {
+      code?: string;
+      killed?: boolean;
+      status?: number;
+      stderr?: unknown;
+      stdout?: unknown;
+    };
 
-    if (error.code === "ETIMEDOUT" || error.killed) {
+    if (execError.code === "ETIMEDOUT" || execError.killed) {
       return {
         success: false,
         output: "",
@@ -79,7 +85,7 @@ export function inference(
       };
     }
 
-    if (error.code === "ENOENT") {
+    if (execError.code === "ENOENT") {
       return {
         success: false,
         output: "",
@@ -89,11 +95,11 @@ export function inference(
     }
 
     // Non-zero exit code
-    if (error.status !== undefined && error.status !== 0) {
+    if (execError.status !== undefined && execError.status !== 0) {
       return {
         success: false,
-        output: (error.stdout ?? "").toString().trim(),
-        error: (error.stderr ?? "").toString().trim() || `Exit code: ${error.status}`,
+        output: String(execError.stdout ?? "").trim(),
+        error: String(execError.stderr ?? "").trim() || `Exit code: ${execError.status}`,
         latency_ms: latencyMs,
       };
     }
@@ -182,7 +188,7 @@ Respond with ONLY a JSON object: {"slug": "your 8-12 word phrase here"}`;
 
 /**
  * Generate a 5-12 word context ID slug from a user prompt.
- * Uses 5.3 Codex Spark first, then falls back to current fast tier for resilience.
+ * Uses Codex Spark first, then falls back to current fast tier for resilience.
  * See SPEC.md §6.3
  */
 export function generateContextIdSlug(
@@ -294,6 +300,47 @@ export async function inferenceAsync(
   return { success: true, output: result.stdout.trim(), latency_ms: latencyMs };
 }
 
+export async function codexInferAsync(
+  prompt: string,
+  model: string,
+  options?: { sandbox?: string; timeout?: number },
+): Promise<InferenceResult> {
+  const startTime = Date.now();
+  const args = ["exec", "--model", model, "--json"];
+  if (options?.sandbox) {
+    args.push("--sandbox", options.sandbox);
+  }
+
+  const result = await execFileAsync(
+    "codex",
+    args,
+    {
+      env: process.env,
+      input: prompt,
+      timeout: (options?.timeout ?? 30) * 1000,
+    },
+  );
+
+  const latencyMs = Date.now() - startTime;
+  if (result.killed) {
+    return { success: false, output: "", error: `Timeout after ${options?.timeout ?? 30}s`, latency_ms: latencyMs };
+  }
+  if (result.exitCode !== 0) {
+    return {
+      success: false,
+      output: result.stdout.trim(),
+      error: result.stderr.trim() || `Exit code: ${result.exitCode}`,
+      latency_ms: latencyMs,
+    };
+  }
+
+  return {
+    success: true,
+    output: result.stdout.trim(),
+    latency_ms: latencyMs,
+  };
+}
+
 /**
  * Filter stop words from text.
  * See SPEC.md §6.4
@@ -305,3 +352,5 @@ function filterStopWords(text: string): string {
     .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
     .join(" ");
 }
+
+

package/dist/templates/{_shared/lib-ts/base → core/lib-ts/runtime}/lint-dispatch.ts

@@ -4,8 +4,9 @@
  * See root CLAUDE.md for template sync targets.
  */
 
+import {spawnSync} from 'node:child_process'
 import * as fs from "node:fs";
-import * as path from "node:path";
+import path from "node:path";
 
 import { logDebug, logWarn } from "./logger.js";
 import { findExecutable } from "./subprocess-utils.js";
@@ -35,14 +36,14 @@ export interface LintError {
 
 function parseBiomeOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
   try {
-    const data = JSON.parse(stdout);
-    const diagnostics: any[] = data?.diagnostics ?? [];
+    const data = JSON.parse(stdout) as { diagnostics?: any[] };
+    const diagnostics = data.diagnostics ?? [];
     return diagnostics.map((d) => ({
       line: d.location?.span?.start?.line ?? d.location?.sourceCode?.lineIndex ?? 0,
       column: d.location?.span?.start?.character ?? undefined,
       severity: d.severity === "error" || d.severity === "fatal" ? "error" as const : "warning" as const,
       message: typeof d.description === "string" ? d.description : (d.message ?? "Unknown issue"),
-      rule: d.category ?? undefined,
+      ...(d.category ? {rule: d.category} : {}),
     }));
   } catch {
     return [];
@@ -51,13 +52,13 @@ function parseBiomeOutput(stdout: string, _stderr: string, _exitCode: number): L
 
 function parseRuffOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
   try {
-    const items: any[] = JSON.parse(stdout);
+    const items = JSON.parse(stdout) as any[];
     return items.map((item) => ({
       line: item.location?.row ?? 0,
       column: item.location?.column ?? undefined,
       severity: "error" as const,
       message: item.message ?? "Unknown issue",
-      rule: item.code ?? undefined,
+      ...(item.code ? {rule: item.code} : {}),
     }));
   } catch {
     return [];
@@ -66,14 +67,14 @@ function parseRuffOutput(stdout: string, _stderr: string, _exitCode: number): Li
 
 function parseShellcheckOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
   try {
-    const data = JSON.parse(stdout);
-    const comments: any[] = data?.comments ?? [];
+    const data = JSON.parse(stdout) as { comments?: any[] };
+    const comments = data.comments ?? [];
     return comments.map((c) => ({
       line: c.line ?? 0,
       column: c.column ?? undefined,
       severity: c.level === "error" ? "error" as const : "warning" as const,
       message: c.message ?? "Unknown issue",
-      rule: c.code ? `SC${c.code}` : undefined,
+      ...(c.code ? {rule: `SC${c.code}`} : {}),
     }));
   } catch {
     return [];
@@ -82,14 +83,14 @@ function parseShellcheckOutput(stdout: string, _stderr: string, _exitCode: numbe
 
 function parseRubocopOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
   try {
-    const data = JSON.parse(stdout);
-    const offenses: any[] = data?.files?.[0]?.offenses ?? [];
+    const data = JSON.parse(stdout) as { files?: Array<{ offenses?: any[] }> };
+    const offenses = data.files?.[0]?.offenses ?? [];
     return offenses.map((o) => ({
       line: o.location?.line ?? 0,
       column: o.location?.column ?? undefined,
       severity: o.severity === "error" || o.severity === "fatal" ? "error" as const : "warning" as const,
       message: o.message ?? "Unknown issue",
-      rule: o.cop_name ?? undefined,
+      ...(o.cop_name ? {rule: o.cop_name} : {}),
     }));
   } catch {
     return [];
@@ -108,7 +109,7 @@ function parseCppcheckOutput(_stdout: string, stderr: string, _exitCode: number)
         column: parseInt(m[3]!, 10),
         severity: m[4] === "error" ? "error" : "warning",
         message: m[5]!,
-        rule: m[6],
+        ...(m[6] ? {rule: m[6]} : {}),
       });
     }
   }
@@ -117,14 +118,14 @@ function parseCppcheckOutput(_stdout: string, stderr: string, _exitCode: number)
 
 function parseEslintOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
   try {
-    const files: any[] = JSON.parse(stdout);
-    const messages: any[] = files?.[0]?.messages ?? [];
+    const files = JSON.parse(stdout) as Array<{ messages?: any[] }>;
+    const messages = files[0]?.messages ?? [];
     return messages.map((m) => ({
       line: m.line ?? 0,
       column: m.column ?? undefined,
       severity: m.severity === 2 ? "error" as const : "warning" as const,
       message: m.message ?? "Unknown issue",
-      rule: m.ruleId ?? undefined,
+      ...(m.ruleId ? {rule: m.ruleId} : {}),
     }));
   } catch {
     return [];
@@ -275,17 +276,16 @@ export function runLinter(
   const args = config.buildArgs(filePath);
 
   try {
-    // eslint-disable-next-line no-undef -- Bun runtime global
-    const result = (Bun as any).spawnSync([binary, ...args], {
+    const result = spawnSync(binary, args, {
       cwd: projectRoot,
       timeout: 8000, // 8s soft limit (10s hook timeout is the hard kill)
-      stdout: "pipe",
-      stderr: "pipe",
+      stdio: 'pipe',
+      encoding: 'utf8',
     });
 
-    const {exitCode} = result;
-    const stdout = result.stdout?.toString() ?? "";
-    const stderr = result.stderr?.toString() ?? "";
+    const exitCode = result.status ?? 1;
+    const stdout = result.stdout ?? "";
+    const stderr = result.stderr ?? "";
 
     // Exit 0 = clean
     if (exitCode === 0) return { errors: [] };
@@ -337,3 +337,5 @@ export function formatLintErrors(
 
   return lines.join("\n");
 }
+
+

package/dist/templates/{_shared/lib-ts/base → core/lib-ts/runtime}/logger.ts

@@ -20,7 +20,7 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
+import path from "node:path";
 
 const LEVELS: Record<string, number> = {
   debug: 0,
@@ -29,7 +29,8 @@ const LEVELS: Record<string, number> = {
   error: 3,
 };
 
-const MAX_LOG_LINES = 10_000; // Max lines in global log before pruning
+const MAX_LOG_BYTES = 2_000_000; // 2MB threshold before pruning
+let _prunedThisProcess = false;
 
 // Module-level session ID cache
 let _cachedSessionId: string | null = null;
@@ -89,7 +90,7 @@ export function hookLog(
   message: string,
   opts?: {
     component?: string;
-    data?: any;
+    data?: unknown;
     traceback_str?: string;
     stderr?: boolean;
   },
@@ -121,7 +122,7 @@ export function hookLog(
     // Build JSONL entry
     const now = new Date();
     const ts = now.toISOString().replace("Z", "").slice(0, 23);
-    const entry: Record<string, any> = {
+    const entry: Record<string, unknown> = {
       ts,
       level: levelLower,
       hook: hookName,
@@ -148,42 +149,41 @@ export function hookLog(
     const dir = path.dirname(logPath);
     fs.mkdirSync(dir, { recursive: true });
 
-    // Line-count guard: prune to last MAX_LOG_LINES
-    try {
-      if (fs.existsSync(logPath)) {
-        const content = fs.readFileSync(logPath, "utf-8");
-        const lines = content.split(/\r?\n/);
-        if (lines.length > MAX_LOG_LINES) {
-          fs.writeFileSync(
-            logPath,
-            lines.slice(lines.length - MAX_LOG_LINES).join("\n"),
-            "utf-8",
-          );
+    // Size-based prune: runs at most once per bun process
+    if (!_prunedThisProcess) {
+      _prunedThisProcess = true;
+      try {
+        const stat = fs.statSync(logPath);
+        if (stat.size > MAX_LOG_BYTES) {
+          const content = fs.readFileSync(logPath, "utf8");
+          const pruneTarget = Math.floor(content.length * 0.1);
+          const keepFrom = content.indexOf("\n", pruneTarget);
+          if (keepFrom > 0) {
+            fs.writeFileSync(logPath, content.slice(keepFrom + 1), "utf8");
+          }
         }
-      }
-    } catch {
-      // ignore
+      } catch { /* file doesn't exist yet — fine */ }
     }
 
-    fs.appendFileSync(logPath, line, "utf-8");
+    fs.appendFileSync(logPath, line, "utf8");
   } catch {
     // Never crash
   }
 }
 
-export function logDebug(hookName: string, message: string, opts?: Record<string, any>): void {
+export function logDebug(hookName: string, message: string, opts?: Record<string, unknown>): void {
   hookLog("debug", hookName, message, opts);
 }
 
-export function logInfo(hookName: string, message: string, opts?: Record<string, any>): void {
+export function logInfo(hookName: string, message: string, opts?: Record<string, unknown>): void {
   hookLog("info", hookName, message, opts);
 }
 
-export function logWarn(hookName: string, message: string, opts?: Record<string, any>): void {
+export function logWarn(hookName: string, message: string, opts?: Record<string, unknown>): void {
   hookLog("warn", hookName, message, opts);
 }
 
-export function logError(hookName: string, message: string, opts?: Record<string, any>): void {
+export function logError(hookName: string, message: string, opts?: Record<string, unknown>): void {
   hookLog("error", hookName, message, opts);
 }
 
@@ -191,7 +191,7 @@ export function logError(hookName: string, message: string, opts?: Record<string
  * Log an error that SHOULD be visible to user/model via stderr.
  * Use for real problems needing attention, not routine diagnostics.
  */
-export function logBlocking(hookName: string, message: string, opts?: Record<string, any>): void {
+export function logBlocking(hookName: string, message: string, opts?: Record<string, unknown>): void {
   hookLog("error", hookName, message, { ...opts, stderr: true });
 }
 
@@ -204,14 +204,14 @@ export function logDiagnostic(
   phase: string,
   summary: string,
   opts?: {
-    inputs?: any;
-    decision?: any;
-    reasoning?: any;
+    inputs?: unknown;
+    decision?: unknown;
+    reasoning?: unknown;
     component?: string;
-    data?: any;
+    data?: unknown;
   },
 ): void {
-  const diagData: Record<string, any> = { phase };
+  const diagData: Record<string, unknown> = { phase };
   if (opts?.inputs !== undefined) diagData.inputs = opts.inputs;
   if (opts?.decision !== undefined) diagData.decision = opts.decision;
   if (opts?.reasoning !== undefined) diagData.reasoning = opts.reasoning;
@@ -245,3 +245,6 @@ export function logHookError(
     stderr: true,
   });
 }
+
+
+

package/dist/templates/{_shared/lib-ts/base → core/lib-ts/runtime}/models.ts

@@ -11,6 +11,6 @@ export const CLAUDE_MODELS = {
 
 export const CODEX_MODELS = {
   spark: "gpt-5.3-codex-spark",
-  codex: "gpt-5.3-codex",
-  gpt: "gpt-5.2",
+  codex: "gpt-5.4",
+  gpt: "gpt-5.4",
 } as const;

package/dist/templates/core/lib-ts/runtime/platform-adapter.ts

@@ -0,0 +1,33 @@
+export type TmuxColorMode = 'c256' | 'truecolor'
+
+export function isWindowsPlatform(platform: NodeJS.Platform = process.platform): boolean {
+  return platform === 'win32'
+}
+
+export function isNonWindowsPlatform(platform: NodeJS.Platform = process.platform): boolean {
+  return !isWindowsPlatform(platform)
+}
+
+export function commandLookupBinary(platform: NodeJS.Platform = process.platform): 'where.exe' | 'which' {
+  return isWindowsPlatform(platform) ? 'where.exe' : 'which'
+}
+
+export function shouldUseShell(platform: NodeJS.Platform = process.platform): boolean {
+  return isWindowsPlatform(platform)
+}
+
+export function resolveTmuxColorModeForPlatform(
+  _platform?: NodeJS.Platform,
+): TmuxColorMode {
+  // Always truecolor — Windows now uses psmux (native ConPTY) which supports truecolor natively.
+  // The c256 degradation was only needed for tmux-via-MSYS2-bash.
+  return 'truecolor'
+}
+
+export function applyTmuxLaunchEnv(
+  envVars: Record<string, string>,
+  _platform?: NodeJS.Platform,
+): Record<string, string> {
+  // Always inject truecolor — psmux on Windows and tmux on Unix both support it.
+  return { COLORTERM: 'truecolor', ...envVars }
+}

package/dist/templates/{_shared/lib-ts/base → core/lib-ts/runtime}/preflight.ts

@@ -1,6 +1,6 @@
 /**
  * Shared preflight health check for provider+model availability.
- * Extracted from plan-review/lib/preflight.ts for reuse by any hook.
+ * Extracted from plan-review/lib/preflight.ts for reuse by unknown hook.
  *
  * Validates that a CLI tool + model combo works by running a minimal "ping" request.
  */
@@ -89,10 +89,11 @@ export async function checkProviderModel(
 
     logDebug(hook, `${provider}:${model} passed (${latencyMs}ms)`);
     return { provider, model, available: true, latencyMs };
-  } catch (err) {
+  } catch (error_) {
     const latencyMs = Date.now() - start;
-    const error = err instanceof Error ? err.message : String(err);
+    const error = error_ instanceof Error ? error_.message : String(error_);
     logWarn(hook, `${provider}:${model} exception: ${error}`);
     return { provider, model, available: false, latencyMs, error };
   }
 }
+

package/dist/templates/core/lib-ts/runtime/sentinel-ipc.ts

@@ -0,0 +1,91 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import 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<void>((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, 'utf8').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, 'utf8')
+}
+
+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.
+  }
+}
+
+