@pushpalsdev/cli 1.0.17 → 1.0.19

package/runtime/sandbox/apps/workerpals/src/backends/shared/test_settings_resolver.py

@@ -0,0 +1,60 @@
+import sys
+import unittest
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+if str(_HERE) not in sys.path:
+    sys.path.insert(0, str(_HERE))
+
+from executor_base import SettingsResolver, build_settings_resolver
+
+
+class SettingsResolverTests(unittest.TestCase):
+    def test_get_str_prefers_env_then_config(self) -> None:
+        resolver = SettingsResolver(
+            env={"A": "  env-value  "},
+            config_loader=lambda: {"root": {"value": "toml-value"}},
+        )
+        value = resolver.get_str(
+            env_names=("A",),
+            config_paths=("root.value",),
+            default="fallback",
+        )
+        self.assertEqual(value, "env-value")
+
+    def test_get_str_uses_first_present_config_path(self) -> None:
+        resolver = SettingsResolver(
+            env={},
+            config_loader=lambda: {"root": {"secondary": "value-2"}},
+        )
+        value = resolver.get_str(
+            config_paths=("root.primary", "root.secondary"),
+            default="fallback",
+        )
+        self.assertEqual(value, "value-2")
+
+    def test_numeric_and_boolean_parsing(self) -> None:
+        resolver = SettingsResolver(
+            env={"INT_ENV": "42", "BOOL_ENV": "true"},
+            config_loader=lambda: {"root": {"int": "9", "enabled": False}},
+        )
+        self.assertEqual(
+            resolver.get_int(env_names=("INT_ENV",), config_paths=("root.int",), default=0),
+            42,
+        )
+        self.assertTrue(
+            resolver.get_bool(env_names=("BOOL_ENV",), config_paths=("root.enabled",), default=False),
+        )
+
+    def test_build_settings_resolver_static_config(self) -> None:
+        resolver = build_settings_resolver(
+            env={"X": ""},
+            config={"root": {"flag": "on"}},
+        )
+        self.assertTrue(
+            resolver.get_bool(env_names=("X",), config_paths=("root.flag",), default=False),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/sandbox/apps/workerpals/src/backends/task_execute_registry.ts

@@ -0,0 +1,21 @@
+import type { ExecutorBackend } from "../common/types.js";
+import type { BackendTaskExecutor } from "./types.js";
+
+export type { BackendTaskExecutor };
+
+const specializedTaskExecutors = new Map<ExecutorBackend, BackendTaskExecutor>();
+
+export function registerBackendTaskExecutor(
+  backend: ExecutorBackend,
+  executor: BackendTaskExecutor,
+): void {
+  specializedTaskExecutors.set(backend, executor);
+}
+
+export function unregisterBackendTaskExecutor(backend: ExecutorBackend): boolean {
+  return specializedTaskExecutors.delete(backend);
+}
+
+export function getBackendTaskExecutor(backend: ExecutorBackend): BackendTaskExecutor | undefined {
+  return specializedTaskExecutors.get(backend);
+}

package/runtime/sandbox/apps/workerpals/src/backends/types.ts

@@ -0,0 +1,52 @@
+import type { ExecutorBackend, JobResult } from "../common/types.js";
+import type { WorkerpalsRuntimeConfig } from "../common/executor_backend.js";
+
+export interface DockerBackendRuntimeConfigType {
+  python: string;
+  timeoutMs: number;
+}
+
+export type DockerBackendRuntimeConfig = Record<string, DockerBackendRuntimeConfigType>;
+
+export interface DockerWarmShellResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface DockerWarmStartupContext {
+  sharedVenvPython: string;
+  warmAgentPort: number;
+  startupAttempts: number;
+  sleepSeconds: string;
+}
+
+export interface DockerWarmRuntimeContext extends DockerWarmStartupContext {
+  warmContainerName: string;
+  runWarmShell: (command: string) => Promise<DockerWarmShellResult>;
+  restartWarmContainer: () => Promise<void>;
+  collectWarmDiagnostics: () => Promise<string>;
+}
+
+export interface DockerBackendSpec {
+  name: ExecutorBackend;
+  configuredPython: (config: DockerBackendRuntimeConfig) => string;
+  timeoutMs: (config: DockerBackendRuntimeConfig) => number;
+  normalizeContainerPython: (configuredPython: string, sharedVenvPython: string) => string;
+  warmContainerStartupCommand: (context: DockerWarmStartupContext) => string;
+  warmContainerEnv: (context: DockerWarmStartupContext) => Record<string, string>;
+  ensureWarmRuntime: ((context: DockerWarmRuntimeContext) => Promise<void>) | null;
+  diagnosticChecks: (sharedVenvPython: string) => Array<{ label: string; command: string }>;
+  warmupProbeCommand: ((sharedVenvPython: string) => string) | null;
+  taskExecute: BackendTaskExecutor;
+}
+
+export type BackendTaskExecutor = (
+  kind: string,
+  params: Record<string, unknown>,
+  repo: string,
+  runtimeConfig: WorkerpalsRuntimeConfig,
+  onLog?: (stream: "stdout" | "stderr", line: string) => void,
+  budgets?: { executionBudgetMs?: number; finalizationBudgetMs?: number },
+) => Promise<JobResult>;

package/runtime/sandbox/apps/workerpals/src/common/execution_utils.ts

@@ -0,0 +1,149 @@
+import { loadPushPalsConfig } from "shared";
+
+const DEFAULT_CONFIG = loadPushPalsConfig();
+
+export interface OutputCompactionPolicy {
+  maxOutputChars: number;
+  maxOutputLines: number;
+  maxOutputHeadLines: number;
+  executorResultPrefix: string;
+}
+
+export function resolveOutputCompactionPolicy(
+  overrides: Partial<OutputCompactionPolicy> = {},
+): OutputCompactionPolicy {
+  const worker = DEFAULT_CONFIG.workerpals;
+  const maxOutputChars = Number(overrides.maxOutputChars ?? worker.outputMaxChars);
+  const maxOutputLines = Number(overrides.maxOutputLines ?? worker.outputMaxLines);
+  const maxOutputHeadLines = Number(overrides.maxOutputHeadLines ?? worker.outputMaxHeadLines);
+  const executorResultPrefixRaw =
+    overrides.executorResultPrefix ?? worker.executorResultPrefix;
+  const executorResultPrefix =
+    typeof executorResultPrefixRaw === "string" && executorResultPrefixRaw.length > 0
+      ? executorResultPrefixRaw
+      : "__PUSHPALS_OH_RESULT__ ";
+
+  return {
+    maxOutputChars:
+      Number.isFinite(maxOutputChars) && maxOutputChars >= 8_192
+        ? Math.min(Math.floor(maxOutputChars), 4_194_304)
+        : 192 * 1024,
+    maxOutputLines:
+      Number.isFinite(maxOutputLines) && maxOutputLines >= 50
+        ? Math.min(Math.floor(maxOutputLines), 20_000)
+        : 600,
+    maxOutputHeadLines:
+      Number.isFinite(maxOutputHeadLines) && maxOutputHeadLines >= 1
+        ? Math.max(1, Math.min(Math.floor(maxOutputHeadLines), Math.floor(maxOutputLines) || 600))
+        : 120,
+    executorResultPrefix,
+  };
+}
+
+// ---- Output truncation -------------------------------------------------------
+
+export function compactJobOutput(text: string, policyOverrides: Partial<OutputCompactionPolicy> = {}): string {
+  if (!text) return "";
+  const policy = resolveOutputCompactionPolicy(policyOverrides);
+  const maxOutputChars = policy.maxOutputChars;
+  const maxOutputLines = policy.maxOutputLines;
+  const maxOutputHeadLines = Math.min(policy.maxOutputHeadLines, maxOutputLines);
+  let compact = text;
+  const lines = compact.split(/\r?\n/);
+  if (lines.length > maxOutputLines) {
+    const headCount = Math.min(maxOutputHeadLines, maxOutputLines, lines.length);
+    const tailBudget = Math.max(0, maxOutputLines - headCount);
+    const tailCount = Math.max(0, Math.min(lines.length - headCount, tailBudget));
+    const omitted = Math.max(0, lines.length - headCount - tailCount);
+    const marker = omitted > 0 ? [`... (${omitted} lines omitted) ...`] : [];
+    const tail = tailCount > 0 ? lines.slice(lines.length - tailCount) : [];
+    compact = [...lines.slice(0, headCount), ...marker, ...tail].join("\n");
+  }
+  if (compact.length > maxOutputChars) {
+    const markerPrefix = "... (";
+    const markerSuffix = " chars omitted) ...\n";
+    const markerBudget = markerPrefix.length + markerSuffix.length + 20;
+    if (markerBudget >= maxOutputChars) {
+      compact = compact.slice(-maxOutputChars);
+    } else {
+      const keepChars = Math.max(0, maxOutputChars - markerBudget);
+      const omittedChars = Math.max(0, compact.length - keepChars);
+      const marker = `${markerPrefix}${omittedChars}${markerSuffix}`;
+      const tail = keepChars > 0 ? compact.slice(-keepChars) : "";
+      compact = `${marker}${tail}`;
+    }
+  }
+  return compact;
+}
+
+export function truncate(s: string, policyOverrides: Partial<OutputCompactionPolicy> = {}): string {
+  return compactJobOutput(s, policyOverrides);
+}
+
+// ---- Stream helper -----------------------------------------------------------
+
+export async function streamLines(
+  readable: ReadableStream<Uint8Array>,
+  streamName: "stdout" | "stderr",
+  onLine: (stream: "stdout" | "stderr", line: string) => void,
+): Promise<string> {
+  const decoder = new TextDecoder();
+  const reader = readable.getReader();
+  let full = "";
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const chunk = decoder.decode(value, { stream: true });
+    full += chunk;
+    buffer += chunk;
+
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      const clean = line.endsWith("\r") ? line.slice(0, -1) : line;
+      onLine(streamName, clean);
+    }
+  }
+
+  if (buffer.length > 0) {
+    const clean = buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+    onLine(streamName, clean);
+  }
+
+  return full;
+}
+
+// ---- Structured result parsing -----------------------------------------------
+
+export function parseStructuredResult(
+  stdout: string,
+  executorResultPrefix = resolveOutputCompactionPolicy().executorResultPrefix,
+): Record<string, unknown> | null {
+  const lines = stdout.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line.startsWith(executorResultPrefix)) continue;
+    const raw = line.slice(executorResultPrefix.length).trim();
+    if (!raw) continue;
+    try {
+      return JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export function filterResultLines(
+  stdout: string,
+  executorResultPrefix = resolveOutputCompactionPolicy().executorResultPrefix,
+): string {
+  return stdout
+    .split(/\r?\n/)
+    .filter((line) => !line.trim().startsWith(executorResultPrefix))
+    .join("\n")
+    .trim();
+}

package/runtime/sandbox/apps/workerpals/src/common/executor_backend.ts

@@ -0,0 +1,15 @@
+import { loadPushPalsConfig } from "shared";
+import type { ExecutorBackend } from "./types.js";
+import { BACKEND_EXECUTOR_SCRIPT_SEGMENTS, DEFAULT_EXECUTOR } from "../backends/backend_config.js";
+
+const DEFAULT_CONFIG = loadPushPalsConfig();
+export type WorkerpalsRuntimeConfig = ReturnType<typeof loadPushPalsConfig>;
+
+export function resolveExecutor(config: WorkerpalsRuntimeConfig = DEFAULT_CONFIG): ExecutorBackend {
+  const raw = config.workerpals.executor.trim().toLowerCase();
+  if (raw in BACKEND_EXECUTOR_SCRIPT_SEGMENTS) return raw as ExecutorBackend;
+  console.warn(
+    `[WorkerPals] Unknown workerpals.executor="${raw}", falling back to "${DEFAULT_EXECUTOR}".`,
+  );
+  return DEFAULT_EXECUTOR;
+}

package/runtime/sandbox/apps/workerpals/src/common/generic_python_executor.ts

@@ -0,0 +1,210 @@
+/**
+ * Factory for a generic Python-wrapper backend task executor.
+ *
+ * Backends that don't need specialized streaming/stuck-guard logic can use
+ * this as their taskExecute implementation. It spawns the backend's Python
+ * script, applies timeout + budget capping, and parses the structured
+ * sentinel result.
+ */
+
+import { existsSync } from "fs";
+import { resolve } from "path";
+import type { JobResult } from "./types.js";
+import type { WorkerpalsRuntimeConfig } from "./executor_backend.js";
+import type { BackendTaskExecutor } from "../backends/types.js";
+import {
+  truncate,
+  parseStructuredResult,
+  filterResultLines,
+  streamLines,
+} from "./execution_utils.js";
+
+interface GenericPythonExecutorConfig {
+  backendName: string;
+  scriptPath: string;
+  pythonConfigKey: string;
+  timeoutConfigKey: string;
+}
+
+function resolveRuntimeSettings(
+  config: GenericPythonExecutorConfig,
+  runtimeConfig: WorkerpalsRuntimeConfig,
+): { pythonBin: string; timeoutMs: number } {
+  const workerCfg = runtimeConfig.workerpals as Record<string, unknown>;
+  const rawPython = String(workerCfg[config.pythonConfigKey] ?? "python");
+  const pythonBin =
+    rawPython.includes("/") || rawPython.includes("\\")
+      ? resolve(runtimeConfig.projectRoot, rawPython)
+      : rawPython;
+  const rawTimeout = Number(workerCfg[config.timeoutConfigKey]);
+  const timeoutMs = Number.isFinite(rawTimeout)
+    ? Math.max(10_000, Math.floor(rawTimeout))
+    : 300_000;
+  return { pythonBin, timeoutMs };
+}
+
+export function createGenericPythonExecutor(
+  config: GenericPythonExecutorConfig,
+): BackendTaskExecutor {
+  const { backendName, scriptPath } = config;
+  const backendLabel = backendName[0].toUpperCase() + backendName.slice(1);
+
+  return async (
+    kind: string,
+    params: Record<string, unknown>,
+    repo: string,
+    runtimeConfig: WorkerpalsRuntimeConfig,
+    onLog?: (stream: "stdout" | "stderr", line: string) => void,
+    budgets?: { executionBudgetMs?: number; finalizationBudgetMs?: number },
+  ): Promise<JobResult> => {
+    if (!existsSync(scriptPath)) {
+      return {
+        ok: false,
+        summary: `${backendName} wrapper script not found: ${scriptPath}`,
+        exitCode: 1,
+      };
+    }
+
+    const { pythonBin, timeoutMs: configuredTimeoutMs } = resolveRuntimeSettings(
+      config,
+      runtimeConfig,
+    );
+    const executionBudgetMs =
+      typeof budgets?.executionBudgetMs === "number" && Number.isFinite(budgets.executionBudgetMs)
+        ? Math.max(10_000, Math.floor(budgets.executionBudgetMs))
+        : null;
+    const timeoutMs =
+      executionBudgetMs != null
+        ? Math.min(configuredTimeoutMs, executionBudgetMs)
+        : configuredTimeoutMs;
+    const payloadBase64 = Buffer.from(
+      JSON.stringify({
+        kind,
+        params,
+        repo,
+      }),
+      "utf-8",
+    ).toString("base64");
+    const args = [pythonBin, scriptPath, payloadBase64];
+
+    onLog?.(
+      "stdout",
+      `[${backendLabel}Executor] Spawning ${backendName} executor (timeout=${timeoutMs}ms)`,
+    );
+
+    try {
+      const outputPolicy = {
+        maxOutputChars: runtimeConfig.workerpals.outputMaxChars,
+        maxOutputLines: runtimeConfig.workerpals.outputMaxLines,
+        maxOutputHeadLines: runtimeConfig.workerpals.outputMaxHeadLines,
+        executorResultPrefix: runtimeConfig.workerpals.executorResultPrefix,
+      };
+      const proc = Bun.spawn(args, {
+        cwd: repo,
+        stdout: "pipe",
+        stderr: "pipe",
+        env: {
+          ...process.env,
+          PUSHPALS_REPO_PATH: repo,
+          PUSHPALS_ASSIGNED_REPO_ROOT: repo,
+          PYTHONIOENCODING: "utf-8",
+        },
+      });
+
+      let timedOut = false;
+      const timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        onLog?.(
+          "stdout",
+          `[${backendLabel}Executor] Timeout reached after ${timeoutMs}ms; terminating process.`,
+        );
+        proc.kill();
+      }, timeoutMs);
+
+      const progressIntervalMs = 15_000;
+      const startedAt = Date.now();
+      let sawProcessOutput = false;
+      const progressTimer = setInterval(() => {
+        if (timedOut || sawProcessOutput) return;
+        const elapsedMs = Math.max(0, Date.now() - startedAt);
+        onLog?.(
+          "stdout",
+          `[${backendLabel}Executor] Still running (${Math.floor(
+            elapsedMs / 1000,
+          )}s elapsed); waiting for executor output...`,
+        );
+      }, progressIntervalMs);
+
+      const onProcessLine = (stream: "stdout" | "stderr", line: string) => {
+        if (!line.trim()) return;
+        sawProcessOutput = true;
+        if (stream === "stdout" && line.startsWith(outputPolicy.executorResultPrefix)) {
+          return;
+        }
+        onLog?.(stream, line);
+      };
+
+      const [rawStdout, rawStderr, exitCode] = await Promise.all([
+        proc.stdout ? streamLines(proc.stdout, "stdout", onProcessLine) : Promise.resolve(""),
+        proc.stderr ? streamLines(proc.stderr, "stderr", onProcessLine) : Promise.resolve(""),
+        proc.exited,
+      ]);
+
+      clearTimeout(timeoutTimer);
+      clearInterval(progressTimer);
+
+      const stdout = rawStdout ?? "";
+      const stderr = rawStderr ?? "";
+
+      const parsed = parseStructuredResult(stdout, outputPolicy.executorResultPrefix);
+      const filteredStdout = filterResultLines(stdout, outputPolicy.executorResultPrefix);
+
+      if (!parsed) {
+        if (timedOut) {
+          return {
+            ok: false,
+            summary: `${backendName} wrapper timed out after ${timeoutMs}ms for ${kind}`,
+            stdout: truncate(filteredStdout, outputPolicy),
+            stderr: truncate(stderr, outputPolicy),
+            exitCode: exitCode === 0 ? 124 : exitCode,
+          };
+        }
+        return {
+          ok: false,
+          summary: `${backendName} wrapper did not return a structured result for ${kind}`,
+          stdout: truncate(filteredStdout, outputPolicy),
+          stderr: truncate(stderr, outputPolicy),
+          exitCode,
+        };
+      }
+
+      return {
+        ok: typeof parsed.ok === "boolean" ? parsed.ok : exitCode === 0,
+        summary:
+          typeof parsed.summary === "string"
+            ? parsed.summary
+            : exitCode === 0
+              ? `${kind} passed via ${backendName}`
+              : `${kind} failed via ${backendName} (exit ${exitCode})`,
+        stdout: truncate(
+          typeof parsed.stdout === "string" ? parsed.stdout : filteredStdout,
+          outputPolicy,
+        ),
+        stderr: truncate(
+          typeof parsed.stderr === "string" ? parsed.stderr : stderr,
+          outputPolicy,
+        ),
+        exitCode:
+          typeof parsed.exitCode === "number" && Number.isFinite(parsed.exitCode)
+            ? parsed.exitCode
+            : exitCode,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        summary: `${backendName} wrapper execution error for ${kind}: ${String(err)}`,
+        exitCode: 1,
+      };
+    }
+  };
+}

package/runtime/sandbox/apps/workerpals/src/common/logger.ts

@@ -0,0 +1,65 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+function normalizeLevel(raw: string): LogLevel | null {
+  const value = raw.trim().toLowerCase();
+  if (value === "debug" || value === "info" || value === "warn" || value === "error") {
+    return value;
+  }
+  return null;
+}
+
+function resolveMinLevel(): LogLevel {
+  const explicit = normalizeLevel(process.env.WORKERPALS_LOG_LEVEL ?? "");
+  if (explicit) return explicit;
+  const debugFlag = (process.env.WORKERPALS_DEBUG ?? "").trim().toLowerCase();
+  return debugFlag === "1" || debugFlag === "true" || debugFlag === "yes" ? "debug" : "info";
+}
+
+export class Logger {
+  private readonly minLevel: LogLevel;
+  private readonly prefix: string;
+
+  constructor(prefix: string, minLevel: LogLevel = resolveMinLevel()) {
+    this.prefix = prefix.trim();
+    this.minLevel = minLevel;
+  }
+
+  isDebugEnabled(): boolean {
+    return this.canLog("debug");
+  }
+
+  debug(message: string): void {
+    if (!this.canLog("debug")) return;
+    console.log(this.format(message));
+  }
+
+  info(message: string): void {
+    if (!this.canLog("info")) return;
+    console.log(this.format(message));
+  }
+
+  warn(message: string): void {
+    if (!this.canLog("warn")) return;
+    console.warn(this.format(message));
+  }
+
+  error(message: string): void {
+    if (!this.canLog("error")) return;
+    console.error(this.format(message));
+  }
+
+  private canLog(level: LogLevel): boolean {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[this.minLevel];
+  }
+
+  private format(message: string): string {
+    return this.prefix ? `[${this.prefix}] ${message}` : message;
+  }
+}

package/runtime/sandbox/apps/workerpals/src/common/types.ts

@@ -0,0 +1,9 @@
+export type ExecutorBackend = string;
+
+export interface JobResult {
+  ok: boolean;
+  summary: string;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+}

package/runtime/sandbox/apps/workerpals/src/common/worktree_cleanup.ts

@@ -0,0 +1,66 @@
+import { existsSync, rmSync } from "fs";
+
+export type WorktreeCleanupOptions = {
+  retries?: number;
+  delayMs?: number;
+  sleepFn?: (ms: number) => Promise<void>;
+  removeFn?: (targetPath: string) => void;
+  existsFn?: (targetPath: string) => boolean;
+};
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function windowsDeletionCandidates(worktreePath: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+
+  const add = (value: string) => {
+    if (!value || seen.has(value)) return;
+    seen.add(value);
+    out.push(value);
+  };
+
+  add(worktreePath);
+
+  if (process.platform === "win32" && /^[A-Za-z]:[\\/]/.test(worktreePath)) {
+    // Long-path literal to avoid MAX_PATH cleanup failures.
+    add(`\\\\?\\${worktreePath}`);
+  }
+
+  return out;
+}
+
+export async function forceDeleteWorktreePath(
+  worktreePath: string,
+  options: WorktreeCleanupOptions = {},
+): Promise<{ removed: boolean; lastError?: string }> {
+  const retries = Math.max(1, Math.floor(options.retries ?? 5));
+  const delayMs = Math.max(0, Math.floor(options.delayMs ?? 120));
+  const sleep = options.sleepFn ?? defaultSleep;
+  const removePath = options.removeFn ?? ((targetPath: string) => rmSync(targetPath, { recursive: true, force: true }));
+  const pathExists = options.existsFn ?? ((targetPath: string) => existsSync(targetPath));
+  let lastError = "";
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    if (!pathExists(worktreePath)) return { removed: true };
+
+    for (const candidate of windowsDeletionCandidates(worktreePath)) {
+      try {
+        removePath(candidate);
+      } catch (error) {
+        lastError = String(error);
+      }
+    }
+
+    if (!pathExists(worktreePath)) return { removed: true };
+    if (attempt < retries) await sleep(delayMs * attempt);
+  }
+
+  return {
+    removed: !pathExists(worktreePath),
+    ...(lastError ? { lastError } : {}),
+  };
+}
+