@2en/clawly-plugins 1.29.0-beta.0 → 1.29.0-beta.1

package/gateway/plugins.ts

@@ -13,6 +13,7 @@ import {$} from 'zx'
 
 import type {PluginApi} from '../types'
 import {LruCache} from '../lib/lruCache'
+import {manualPluginInstall} from '../lib/manualPluginInstall'
 import {captureEvent} from './posthog'
 import {isUpdateAvailable} from '../lib/semver'
 import {stripCliLogs} from '../lib/stripCliLogs'
@@ -61,301 +62,6 @@ async function fetchNpmView(npmPkgName: string): Promise<NpmViewCache | null> {
   }
 }
 
-const BACKUP_DIR_SUFFIX = '.update-backup'
-const LEGACY_BACKUP_ZIP_SUFFIX = '.update-backup.zip'
-const STAGING_DIR_PREFIX = '.staging-'
-
-/**
- * Back up plugin dir before an install/update operation, verify the sentinel
- * file exists after, and rollback from backup on failure.
- *
- * Two modes:
- * - **staging** (default): Install to a staging dir under extensions/, then do
- *   two fast renames to swap dirs. The plugin dir is only missing for
- *   microseconds between renames, not for the entire npm install duration.
- * - **in-place** (`staging: false`): Copy-based backup for in-place operations
- *   like `openclaw plugins update`. The original dir stays live during the
- *   operation; rollback restores from the copy.
- */
-async function withPluginBackup<T>(
-  api: PluginApi,
-  pluginId: string,
-  operation: (ctx: {stagingDir?: string}) => Promise<T>,
-  opts?: {staging?: boolean},
-): Promise<T> {
-  const stateDir = api.runtime.state.resolveStateDir()
-  if (!stateDir) return operation({})
-
-  const extensionsBase = path.join(stateDir, 'extensions')
-  const extensionDir = path.join(extensionsBase, pluginId)
-  const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-  const useStaging = opts?.staging !== false
-
-  if (useStaging) {
-    return withStagingInstall(
-      api,
-      {stateDir, extensionsBase, extensionDir, backupDir, pluginId},
-      operation,
-    )
-  }
-  return withInPlaceBackup(api, {extensionDir, backupDir, pluginId}, operation)
-}
-
-async function withStagingInstall<T>(
-  api: PluginApi,
-  dirs: {
-    stateDir: string
-    extensionsBase: string
-    extensionDir: string
-    backupDir: string
-    pluginId: string
-  },
-  operation: (ctx: {stagingDir?: string}) => Promise<T>,
-): Promise<T> {
-  const {extensionsBase, extensionDir, backupDir, pluginId} = dirs
-
-  // Clean any orphaned staging dirs from previous interrupted attempts
-  cleanOrphanedStagingDirs(api, pluginId)
-
-  const suffix = crypto.randomBytes(4).toString('hex')
-  const stagingDir = path.join(extensionsBase, `${STAGING_DIR_PREFIX}${pluginId}-${suffix}`)
-
-  // Create staging dir (same filesystem as extensions/ → renameSync is atomic)
-  fs.mkdirSync(stagingDir, {recursive: true})
-
-  try {
-    const result = await operation({stagingDir})
-
-    // Verify sentinel in staging output
-    const stagedPluginDir = path.join(stagingDir, 'extensions', pluginId)
-    if (!fs.existsSync(path.join(stagedPluginDir, PLUGIN_SENTINEL))) {
-      throw new Error(
-        `plugin files missing after operation (${PLUGIN_SENTINEL} not found in staging)`,
-      )
-    }
-
-    // Atomic swap: rename existing → backup, then staging → final
-    const hasExisting = fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))
-    if (hasExisting) {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-      fs.renameSync(extensionDir, backupDir)
-    } else if (fs.existsSync(extensionDir)) {
-      // Broken dir without sentinel — remove it
-      fs.rmSync(extensionDir, {recursive: true, force: true})
-    }
-
-    fs.renameSync(stagedPluginDir, extensionDir)
-    api.logger.info(`plugins: staged install of ${pluginId} swapped in`)
-
-    // Cleanup staging dir + backup — failure must not trigger rollback
-    try {
-      fs.rmSync(stagingDir, {recursive: true, force: true})
-    } catch {}
-    try {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-    } catch (cleanupErr) {
-      api.logger.warn(
-        `plugins: failed to clean backup dir — ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`,
-      )
-    }
-
-    return result
-  } catch (err) {
-    // Clean up staging dir on failure — original is untouched
-    try {
-      if (fs.existsSync(stagingDir)) fs.rmSync(stagingDir, {recursive: true, force: true})
-    } catch {}
-
-    // If we already renamed the original away (crash between step 3 and 4),
-    // the backup exists — restore it
-    if (fs.existsSync(backupDir) && !fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))) {
-      api.logger.warn(`plugins: rolling back ${pluginId} from backup`)
-      try {
-        if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-        fs.renameSync(backupDir, extensionDir)
-        api.logger.info(`plugins: rollback complete`)
-      } catch (rollbackErr) {
-        api.logger.error(
-          `plugins: rollback failed — ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
-        )
-      }
-    }
-    throw err
-  }
-}
-
-async function withInPlaceBackup<T>(
-  api: PluginApi,
-  dirs: {extensionDir: string; backupDir: string; pluginId: string},
-  operation: (ctx: {stagingDir?: string}) => Promise<T>,
-): Promise<T> {
-  const {extensionDir, backupDir, pluginId} = dirs
-
-  const hasExisting = fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))
-  if (hasExisting) {
-    try {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-      fs.cpSync(extensionDir, backupDir, {recursive: true})
-      api.logger.info(`plugins: backed up ${pluginId} (in-place)`)
-    } catch (err) {
-      throw new Error(
-        `plugin backup failed, aborting update: ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-  }
-
-  try {
-    const result = await operation({})
-
-    if (!fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))) {
-      if (!hasExisting && fs.existsSync(extensionDir)) {
-        try {
-          fs.rmSync(extensionDir, {recursive: true, force: true})
-        } catch {}
-      }
-      throw new Error(`plugin files missing after operation (${PLUGIN_SENTINEL} not found)`)
-    }
-
-    // Clean backup on success
-    try {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-    } catch (cleanupErr) {
-      api.logger.warn(
-        `plugins: failed to clean backup dir — ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`,
-      )
-    }
-
-    return result
-  } catch (err) {
-    // Clean up partial install on first-time failure (no backup to restore)
-    if (!hasExisting && fs.existsSync(extensionDir)) {
-      try {
-        fs.rmSync(extensionDir, {recursive: true, force: true})
-      } catch {}
-    }
-
-    if (fs.existsSync(backupDir)) {
-      api.logger.warn(`plugins: rolling back ${pluginId} from backup`)
-      try {
-        if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-        fs.renameSync(backupDir, extensionDir)
-        api.logger.info(`plugins: rollback complete`)
-      } catch (rollbackErr) {
-        api.logger.error(
-          `plugins: rollback failed — ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
-        )
-      }
-    } else {
-      const legacyZip = `${extensionDir}${LEGACY_BACKUP_ZIP_SUFFIX}`
-      if (fs.existsSync(legacyZip)) {
-        api.logger.warn(`plugins: rolling back ${pluginId} from legacy zip backup`)
-        try {
-          if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-          await $`unzip -qo ${legacyZip} -d ${path.dirname(extensionDir)}`
-          fs.unlinkSync(legacyZip)
-          api.logger.info(`plugins: rollback from legacy zip complete`)
-        } catch (rollbackErr) {
-          api.logger.error(
-            `plugins: legacy zip rollback failed — ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
-          )
-        }
-      }
-    }
-    throw err
-  }
-}
-
-/**
- * Clean up orphaned staging dirs left by interrupted installs.
- * Staging dirs are named `.staging-<pluginId>-<hex>` under extensions/.
- */
-function cleanOrphanedStagingDirs(api: PluginApi, pluginId: string): void {
-  const stateDir = api.runtime.state.resolveStateDir()
-  if (!stateDir) return
-
-  const extensionsBase = path.join(stateDir, 'extensions')
-  try {
-    const entries = fs.readdirSync(extensionsBase)
-    const pattern = new RegExp(
-      `^${STAGING_DIR_PREFIX}${pluginId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-[0-9a-f]{8}$`,
-    )
-    for (const entry of entries) {
-      if (pattern.test(entry)) {
-        try {
-          fs.rmSync(path.join(extensionsBase, entry), {recursive: true, force: true})
-          api.logger.info(`plugins: cleaned up orphaned staging dir ${entry}`)
-        } catch {}
-      }
-    }
-  } catch {}
-}
-
-/**
- * Recover from orphaned backups left by interrupted updates.
- * Called during plugin registration (startup).
- */
-async function recoverOrphanedBackup(api: PluginApi, pluginId: string): Promise<void> {
-  const stateDir = api.runtime.state.resolveStateDir()
-  if (!stateDir) return
-
-  // Clean orphaned staging dirs first
-  cleanOrphanedStagingDirs(api, pluginId)
-
-  const extensionDir = path.join(stateDir, 'extensions', pluginId)
-  const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-  const legacyZip = `${extensionDir}${LEGACY_BACKUP_ZIP_SUFFIX}`
-  const sentinelExists = fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))
-
-  if (sentinelExists) {
-    // Plugin dir is healthy — clean up any stale backups
-    if (fs.existsSync(backupDir)) {
-      try {
-        fs.rmSync(backupDir, {recursive: true, force: true})
-        api.logger.info(`plugins: cleaned up stale backup dir for ${pluginId}`)
-      } catch {}
-    }
-    if (fs.existsSync(legacyZip)) {
-      try {
-        fs.unlinkSync(legacyZip)
-        api.logger.info(`plugins: cleaned up stale legacy backup zip for ${pluginId}`)
-      } catch {}
-    }
-    return
-  }
-
-  // Plugin dir is missing or broken — try to recover from backup
-  if (fs.existsSync(backupDir)) {
-    api.logger.warn(`plugins: recovering ${pluginId} from orphaned backup dir`)
-    try {
-      if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-      fs.renameSync(backupDir, extensionDir)
-      if (!fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))) {
-        api.logger.warn(
-          `plugins: recovered dir for ${pluginId} is missing sentinel — plugin may still be broken`,
-        )
-      } else {
-        api.logger.info(`plugins: recovery from orphaned backup complete`)
-      }
-    } catch (err) {
-      api.logger.error(
-        `plugins: orphaned backup recovery failed — ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-  } else if (fs.existsSync(legacyZip)) {
-    api.logger.warn(`plugins: recovering ${pluginId} from orphaned legacy zip backup`)
-    try {
-      if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-      await $`unzip -qo ${legacyZip} -d ${path.join(stateDir, 'extensions')}`
-      fs.unlinkSync(legacyZip)
-      api.logger.info(`plugins: recovery from orphaned legacy zip complete`)
-    } catch (err) {
-      api.logger.error(
-        `plugins: legacy zip recovery failed — ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-  }
-}
-
 interface UpdateParams {
   pluginId: string
   npmPkgName: string
@@ -372,24 +78,7 @@ interface UpdateParams {
   skipIfCurrent?: boolean
 }
 
-// Exported for testing
-export {
-  withPluginBackup,
-  recoverOrphanedBackup,
-  cleanOrphanedStagingDirs,
-  BACKUP_DIR_SUFFIX,
-  LEGACY_BACKUP_ZIP_SUFFIX,
-  STAGING_DIR_PREFIX,
-}
-
 export function registerPlugins(api: PluginApi) {
-  // ── Startup recovery for orphaned backups ──────────────────────
-  void recoverOrphanedBackup(api, 'clawly-plugins').catch((err) => {
-    api.logger.error(
-      `plugins: orphaned backup recovery crashed — ${err instanceof Error ? err.message : String(err)}`,
-    )
-  })
-
   // ── clawly.plugins.version ──────────────────────────────────────
 
   api.registerGatewayMethod('clawly.plugins.version', async ({params, respond}) => {
@@ -524,69 +213,23 @@ export function registerPlugins(api: PluginApi) {
     try {
       let output = ''
 
-      if (strategy === 'force') {
-        if (!stateDir) throw new Error('cannot resolve openclaw state dir')
+      if (!stateDir) throw new Error('cannot resolve openclaw state dir')
 
-        const configPath = path.join(stateDir, 'openclaw.json')
-
-        // 1. Save current plugins.entries.<id> config (preserve user settings)
-        let savedEntry: Record<string, unknown> = {enabled: true}
-        try {
-          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
-          const entry = config?.plugins?.entries?.[pluginId]
-          if (entry && typeof entry === 'object') {
-            savedEntry = entry as Record<string, unknown>
-          }
-        } catch {
-          // config unreadable — use default
-        }
-        api.logger.info(`plugins: force — saved entry config for ${pluginId}`)
-
-        // 2. Install to staging dir (OPENCLAW_STATE_DIR gives clean slate),
-        //    then atomic swap — no config write needed before install.
-        output = await withPluginBackup(api, pluginId, async ({stagingDir}) => {
-          api.logger.info(`plugins: force — installing ${installTarget} to staging dir`)
-          const result = stagingDir
-            ? await $`OPENCLAW_STATE_DIR=${stagingDir} openclaw plugins install ${installTarget}`
-            : await $`openclaw plugins install ${installTarget}`
-          return result.stdout.trim()
-        })
+      const targetDir = path.join(stateDir, 'extensions', pluginId)
+      const stagingDir = path.join(
+        stateDir,
+        'clawly',
+        'staging',
+        `${pluginId}-${crypto.randomBytes(4).toString('hex')}`,
+      )
 
-        // 3. Ensure config entry is present (triggers config watcher → restart)
-        try {
-          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
-          if (!config.plugins) config.plugins = {}
-          if (!config.plugins.entries) config.plugins.entries = {}
-          config.plugins.entries[pluginId] = {
-            ...config.plugins.entries[pluginId],
-            ...savedEntry,
-          }
-          fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
-          api.logger.info(`plugins: force — ensured entry config for ${pluginId}`)
-        } catch (err) {
-          api.logger.warn(
-            `plugins: force — failed to write entry config: ${err instanceof Error ? err.message : String(err)}`,
-          )
-        }
-      } else if (strategy === 'update') {
-        output = await withPluginBackup(
-          api,
-          pluginId,
-          async () => {
-            const result = await $`openclaw plugins update ${pluginId}`
-            return result.stdout.trim()
-          },
-          {staging: false},
-        )
-      } else {
-        // install
-        output = await withPluginBackup(api, pluginId, async ({stagingDir}) => {
-          const result = stagingDir
-            ? await $`OPENCLAW_STATE_DIR=${stagingDir} openclaw plugins install ${installTarget}`
-            : await $`openclaw plugins install ${installTarget}`
-          return result.stdout.trim()
-        })
-      }
+      api.logger.info(`plugins: ${strategy} — installing ${installTarget}`)
+      output = await manualPluginInstall({
+        spec: installTarget,
+        targetDir,
+        stagingDir,
+        logger: api.logger,
+      })
 
       // Invalidate npm cache for this package
       npmCache.delete(npmPkgName)

package/gateway/presence.ts

@@ -13,7 +13,6 @@ import {stripCliLogs} from '../lib/stripCliLogs'
 $.verbose = false
 
 const DEFAULT_HOST = 'openclaw-ios'
-const CLAWLY_MOBILE_PREFIX = 'Clawly Mobile'
 
 interface PresenceEntry {
   host?: string
@@ -39,9 +38,7 @@ export async function isClientOnline(host = DEFAULT_HOST): Promise<boolean> {
     const result = await $`openclaw gateway call system-presence --json`
     const jsonStr = stripCliLogs(result.stdout)
     const entries: PresenceEntry[] = JSON.parse(jsonStr)
-    const entry =
-      entries.find((e) => e.host === host) ||
-      entries.find((e) => e.host?.startsWith(CLAWLY_MOBILE_PREFIX))
+    const entry = entries.find((e) => e.host === host)
     return isOnlineEntry(entry)
   } catch {
     return false

package/lib/manualPluginInstall.test.ts

@@ -0,0 +1,121 @@
+import {afterEach, beforeEach, describe, expect, test} from 'bun:test'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import {manualPluginInstall} from './manualPluginInstall'
+
+const PLUGIN_ID = 'test-plugin'
+const SENTINEL = 'openclaw.plugin.json'
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'clawly-plugins-test-'))
+}
+
+function setupPluginDir(stateDir: string): string {
+  const extensionDir = path.join(stateDir, 'extensions', PLUGIN_ID)
+  fs.mkdirSync(extensionDir, {recursive: true})
+  fs.writeFileSync(path.join(extensionDir, SENTINEL), '{}')
+  fs.writeFileSync(path.join(extensionDir, 'package.json'), '{"version":"1.0.0"}')
+  return extensionDir
+}
+
+function setupLocalSpec(tmpDir: string, version: string, hasSentinel = true): string {
+  const specDir = path.join(tmpDir, 'local-spec')
+  fs.mkdirSync(specDir, {recursive: true})
+  if (hasSentinel) fs.writeFileSync(path.join(specDir, SENTINEL), '{}')
+  fs.writeFileSync(path.join(specDir, 'package.json'), `{"version":"${version}"}`)
+  return specDir
+}
+
+let tmpDir: string
+
+beforeEach(() => {
+  tmpDir = makeTmpDir()
+})
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true})
+})
+
+describe('manualPluginInstall', () => {
+  test('first install (empty targetDir): installs from local spec', async () => {
+    const targetDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '1.0.0')
+
+    const result = await manualPluginInstall({
+      spec: specDir,
+      targetDir,
+      stagingDir,
+    })
+
+    expect(result).toContain('Installed')
+    expect(fs.existsSync(path.join(targetDir, SENTINEL))).toBe(true)
+    expect(JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8')).version).toBe(
+      '1.0.0',
+    )
+    expect(fs.existsSync(stagingDir)).toBe(false)
+  })
+
+  test('update: syncs new version, removes stale files, cleans staging', async () => {
+    const targetDir = setupPluginDir(tmpDir)
+    fs.writeFileSync(path.join(targetDir, 'feature-v1.js'), 'old')
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '2.0.0')
+
+    const result = await manualPluginInstall({
+      spec: specDir,
+      targetDir,
+      stagingDir,
+    })
+
+    expect(result).toContain('Installed')
+    expect(fs.existsSync(path.join(targetDir, 'feature-v1.js'))).toBe(false)
+    expect(fs.existsSync(path.join(targetDir, SENTINEL))).toBe(true)
+    expect(JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8')).version).toBe(
+      '2.0.0',
+    )
+    expect(fs.existsSync(stagingDir)).toBe(false)
+  })
+
+  test('rejects when spec lacks sentinel (targetDir unchanged)', async () => {
+    const targetDir = setupPluginDir(tmpDir)
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '2.0.0', false)
+
+    await expect(manualPluginInstall({spec: specDir, targetDir, stagingDir})).rejects.toThrow(
+      'plugin source missing openclaw.plugin.json',
+    )
+
+    expect(fs.existsSync(path.join(targetDir, SENTINEL))).toBe(true)
+    expect(JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8')).version).toBe(
+      '1.0.0',
+    )
+  })
+
+  test('first install: rejects when spec lacks sentinel (targetDir left empty)', async () => {
+    const targetDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
+    fs.mkdirSync(path.join(tmpDir, 'extensions'), {recursive: true})
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '1.0.0', false)
+
+    await expect(manualPluginInstall({spec: specDir, targetDir, stagingDir})).rejects.toThrow(
+      'plugin source missing openclaw.plugin.json',
+    )
+
+    expect(fs.existsSync(targetDir)).toBe(true)
+    expect(fs.readdirSync(targetDir)).toHaveLength(0)
+  })
+
+  test('local spec path must exist', async () => {
+    const targetDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
+    fs.mkdirSync(targetDir, {recursive: true})
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = path.join(tmpDir, 'nonexistent')
+
+    await expect(manualPluginInstall({spec: specDir, targetDir, stagingDir})).rejects.toThrow(
+      'local spec path does not exist',
+    )
+  })
+})

package/lib/manualPluginInstall.ts

@@ -0,0 +1,148 @@
+/**
+ * Manual plugin install that bypasses OpenClaw's hardened extraction pipeline.
+ *
+ * OpenClaw ≥3.12 uses `copyFileWithinRoot` → `runPinnedWriteHelper` (python3)
+ * during tar extraction, which fails on sprite overlay/JuiceFS filesystems
+ * with `SafeOpenError: path is not a regular file under root`.
+ *
+ * Supports both npm spec and local absolute path. Install uses rsync:
+ * `rsync -a --delete` syncs source into targetDir — overwrites changed files,
+ * adds new files, and removes stale files not in source. The target directory
+ * is never moved or deleted, so the plugin stays functional during the sync.
+ * Staging artifacts (tgz, pkg) are cleaned up in finally.
+ */
+
+import assert from 'node:assert'
+import fs from 'node:fs'
+import path from 'node:path'
+import {$} from 'zx'
+
+const PLUGIN_SENTINEL = 'openclaw.plugin.json'
+
+interface Logger {
+  info?: (msg: string) => void
+  warn?: (msg: string) => void
+  error?: (msg: string) => void
+}
+
+async function withRetry<T>(fn: () => Promise<T>, maxAttempts: number): Promise<T> {
+  let lastErr: unknown
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (err) {
+      lastErr = err
+      if (attempt < maxAttempts) {
+        await new Promise((r) => setTimeout(r, 500 * attempt))
+      }
+    }
+  }
+  throw lastErr
+}
+
+export async function manualPluginInstall(params: {
+  spec: string
+  targetDir: string
+  stagingDir: string
+  logger?: Logger
+}): Promise<string> {
+  const {spec, targetDir, stagingDir, logger} = params
+  const isNpm = !path.isAbsolute(spec)
+  const pkgDir = path.join(stagingDir, 'pkg')
+
+  // 1. Ensure targetDir exists
+  fs.mkdirSync(targetDir, {recursive: true})
+
+  // 2. Create stagingDir
+  fs.mkdirSync(stagingDir, {recursive: true})
+
+  try {
+    let sourceDir: string
+    if (isNpm) {
+      // 3a. npm pack → stagingDir (retry 3x)
+      logger?.info?.(`downloading ${spec}...`)
+      const packResult = await withRetry(async () => {
+        const result = await $`npm pack ${spec} --pack-destination ${stagingDir}`
+        return result
+      }, 3)
+      const lastLine = packResult.stdout.trim().split('\n').pop() ?? ''
+      const tgzName = path.basename(lastLine)
+      if (!tgzName.endsWith('.tgz')) throw new Error(`unexpected npm pack output: ${lastLine}`)
+      const tgzPath = path.join(stagingDir, tgzName)
+
+      try {
+        // 3b. Extract to stagingDir/pkg
+        fs.mkdirSync(pkgDir, {recursive: true})
+        logger?.info?.(`extracting to ${pkgDir}...`)
+        await $`tar xzf ${tgzPath} --strip-components=1 -C ${pkgDir}`
+      } finally {
+        try {
+          fs.unlinkSync(tgzPath)
+        } catch {}
+      }
+
+      // 3c. npm install in pkg (retry 3x)
+      const pkgPath = path.join(pkgDir, 'package.json')
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+        if (pkg.dependencies && Object.keys(pkg.dependencies).length > 0) {
+          logger?.info?.('installing dependencies...')
+          await withRetry(
+            () => $({cwd: pkgDir})`npm install --omit=dev --omit=peer --ignore-scripts`,
+            3,
+          )
+        }
+      }
+      sourceDir = pkgDir
+    } else {
+      sourceDir = spec
+      if (!fs.existsSync(sourceDir)) {
+        throw new Error(`local spec path does not exist: ${sourceDir}`)
+      }
+    }
+
+    assert(
+      fs.existsSync(path.join(sourceDir, 'package.json')),
+      `plugin source missing package.json: ${sourceDir}`,
+    )
+    assert(
+      fs.existsSync(path.join(sourceDir, PLUGIN_SENTINEL)),
+      `plugin source missing openclaw.plugin.json: ${sourceDir}`,
+    )
+
+    // 4. rsync source → targetDir (overlay + delete stale files)
+    // npm pack output is already clean; local path needs dev file exclusions
+    logger?.info?.(`syncing to ${targetDir}...`)
+    if (isNpm) {
+      await $`rsync -a --delete --checksum ${sourceDir}/ ${targetDir}/`
+    } else {
+      await $`rsync -a --delete --checksum --exclude=node_modules --exclude=.git ${sourceDir}/ ${targetDir}/`
+    }
+
+    // 5. Verify sentinel
+    if (!fs.existsSync(path.join(targetDir, PLUGIN_SENTINEL))) {
+      throw new Error(`plugin files missing after install (${PLUGIN_SENTINEL} not found)`)
+    }
+
+    // 6. Local path: install production deps (rsync excludes node_modules)
+    if (!isNpm) {
+      const pkg = JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8'))
+      if (pkg.dependencies && Object.keys(pkg.dependencies).length > 0) {
+        logger?.info?.('installing dependencies...')
+        await withRetry(
+          () => $({cwd: targetDir})`npm install --omit=dev --omit=peer --ignore-scripts`,
+          3,
+        )
+      }
+    }
+
+    return `Installed ${spec} to ${targetDir}`
+  } finally {
+    // 6. Remove stagingDir (tgz + pkg artifacts)
+    try {
+      if (fs.existsSync(stagingDir)) {
+        fs.rmSync(stagingDir, {recursive: true, force: true})
+      }
+    } catch {}
+  }
+}

package/openclaw.plugin.json

@@ -3,6 +3,7 @@
   "name": "Clawly Plugins",
   "description": "Clawly utility RPC methods (clawly.*): file access, presence, push notifications, agent messaging, memory browser, and ClawHub CLI bridge.",
   "version": "0.3.0",
+  "skills": ["skills/read-office-file"],
   "uiHints": {
     "memoryDir": {
       "label": "Memory directory",

package/outbound.ts

@@ -190,6 +190,18 @@ export function registerOutboundHttpRoute(api: PluginApi) {
     path: '/clawly/file/outbound',
     auth: 'plugin',
     handler: async (_req: IncomingMessage, res: ServerResponse) => {
+      res.setHeader('Access-Control-Allow-Origin', '*')
+
+      // Handle CORS preflight
+      if (_req.method === 'OPTIONS') {
+        res.setHeader('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS')
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
+        res.setHeader('Access-Control-Max-Age', '86400')
+        res.statusCode = 204
+        res.end()
+        return
+      }
+
       const url = new URL(_req.url ?? '/', 'http://localhost')
       if (!guardHttpAuth(api, _req, res, url)) return
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.29.0-beta.0",
+  "version": "1.29.0-beta.1",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -36,7 +36,8 @@
     "resolve-gateway-credentials.ts",
     "skill-command-restore.ts",
     "openclaw.plugin.json",
-    "internal"
+    "internal",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"

package/skills/read-office-file/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: read-office-file
+description: Convert Word, Excel, or PowerPoint files to Markdown using MarkItDown.
+metadata: { "openclaw": { "emoji": "📄" } }
+---
+
+# Read Office File
+
+Convert Word (.docx), Excel (.xlsx), or PowerPoint (.pptx) files to Markdown using [MarkItDown](https://github.com/microsoft/markitdown).
+
+## When to use
+
+- User asks to read, summarize, or extract content from a `.docx`, `.xlsx`, or `.pptx` file.
+- User shares or references an Office file path.
+
+## Steps
+
+1. Convert the file to Markdown (use the extra matching the file type):
+
+```bash
+# .docx
+uvx 'markitdown[docx]' <file_path>
+
+# .xlsx
+uvx 'markitdown[xlsx]' <file_path>
+
+# .pptx
+uvx 'markitdown[pptx]' <file_path>
+```
+
+2. Read the Markdown output and respond to the user's request.
+
+## Supported formats
+
+| Format | Extensions |
+|---|---|
+| Word | `.docx` |
+| Excel | `.xlsx` |
+| PowerPoint | `.pptx` |
+
+Legacy formats (`.doc`, `.xls`, `.ppt`) are **not supported**. Ask the user to convert to the modern format first.

package/gateway/plugins.test.ts

@@ -1,472 +0,0 @@
-import {afterEach, beforeEach, describe, expect, test} from 'bun:test'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-
-import {
-  withPluginBackup,
-  recoverOrphanedBackup,
-  cleanOrphanedStagingDirs,
-  BACKUP_DIR_SUFFIX,
-  LEGACY_BACKUP_ZIP_SUFFIX,
-  STAGING_DIR_PREFIX,
-} from './plugins'
-import type {PluginApi} from '../types'
-
-const PLUGIN_ID = 'test-plugin'
-const SENTINEL = 'openclaw.plugin.json'
-
-function makeTmpDir(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'clawly-plugins-test-'))
-}
-
-function makeApi(stateDir: string): PluginApi {
-  const logs: string[] = []
-  return {
-    id: 'test',
-    name: 'test',
-    runtime: {state: {resolveStateDir: () => stateDir}},
-    logger: {
-      info: (msg: string) => logs.push(`info: ${msg}`),
-      warn: (msg: string) => logs.push(`warn: ${msg}`),
-      error: (msg: string) => logs.push(`error: ${msg}`),
-    },
-    registerGatewayMethod: () => {},
-    registerTool: () => {},
-    registerCommand: () => {},
-    registerChannel: () => {},
-    registerHttpRoute: () => {},
-    on: () => {},
-    _logs: logs,
-  } as unknown as PluginApi & {_logs: string[]}
-}
-
-function setupPluginDir(stateDir: string): string {
-  const extensionDir = path.join(stateDir, 'extensions', PLUGIN_ID)
-  fs.mkdirSync(extensionDir, {recursive: true})
-  fs.writeFileSync(path.join(extensionDir, SENTINEL), '{}')
-  fs.writeFileSync(path.join(extensionDir, 'package.json'), '{"version":"1.0.0"}')
-  return extensionDir
-}
-
-/** Simulate openclaw plugins install writing to a staging dir */
-function simulateStagedInstall(stagingDir: string, pluginId: string, version: string) {
-  const stagedPluginDir = path.join(stagingDir, 'extensions', pluginId)
-  fs.mkdirSync(stagedPluginDir, {recursive: true})
-  fs.writeFileSync(path.join(stagedPluginDir, SENTINEL), '{}')
-  fs.writeFileSync(path.join(stagedPluginDir, 'package.json'), JSON.stringify({version}))
-}
-
-let tmpDir: string
-
-beforeEach(() => {
-  tmpDir = makeTmpDir()
-})
-
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true})
-})
-
-describe('withPluginBackup (staging mode — default)', () => {
-  test('successful install: original stays live during operation, atomic swap at end', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-    const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-
-    const result = await withPluginBackup(api, PLUGIN_ID, async ({stagingDir}) => {
-      // Original dir should still exist during the operation
-      expect(fs.existsSync(extensionDir)).toBe(true)
-      expect(fs.existsSync(path.join(extensionDir, SENTINEL))).toBe(true)
-      // Staging dir should be provided and exist
-      expect(stagingDir).toBeDefined()
-      expect(fs.existsSync(stagingDir!)).toBe(true)
-      // Staging dir should be under extensions/
-      expect(stagingDir!.startsWith(path.join(tmpDir, 'extensions'))).toBe(true)
-
-      simulateStagedInstall(stagingDir!, PLUGIN_ID, '2.0.0')
-      return 'installed'
-    })
-
-    expect(result).toBe('installed')
-    expect(fs.existsSync(extensionDir)).toBe(true)
-    expect(fs.existsSync(backupDir)).toBe(false)
-    expect(
-      JSON.parse(fs.readFileSync(path.join(extensionDir, 'package.json'), 'utf-8')).version,
-    ).toBe('2.0.0')
-    // Staging dir should be cleaned up
-    const remainingStaging = fs
-      .readdirSync(path.join(tmpDir, 'extensions'))
-      .filter((f) => f.startsWith(STAGING_DIR_PREFIX))
-    expect(remainingStaging).toHaveLength(0)
-  })
-
-  test('failed install: original dir untouched, staging dir cleaned up', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-
-    await expect(
-      withPluginBackup(api, PLUGIN_ID, async ({stagingDir}) => {
-        expect(fs.existsSync(extensionDir)).toBe(true)
-        expect(stagingDir).toBeDefined()
-        throw new Error('npm install failed')
-      }),
-    ).rejects.toThrow('npm install failed')
-
-    // Original dir should be untouched
-    expect(fs.existsSync(extensionDir)).toBe(true)
-    expect(fs.existsSync(path.join(extensionDir, SENTINEL))).toBe(true)
-    expect(
-      JSON.parse(fs.readFileSync(path.join(extensionDir, 'package.json'), 'utf-8')).version,
-    ).toBe('1.0.0')
-    // No staging dirs left
-    const remainingStaging = fs
-      .readdirSync(path.join(tmpDir, 'extensions'))
-      .filter((f) => f.startsWith(STAGING_DIR_PREFIX))
-    expect(remainingStaging).toHaveLength(0)
-  })
-
-  test('missing sentinel in staging: throws, original untouched', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-
-    await expect(
-      withPluginBackup(api, PLUGIN_ID, async ({stagingDir}) => {
-        // Install to staging but forget sentinel
-        const stagedPluginDir = path.join(stagingDir!, 'extensions', PLUGIN_ID)
-        fs.mkdirSync(stagedPluginDir, {recursive: true})
-        fs.writeFileSync(path.join(stagedPluginDir, 'package.json'), '{"version":"2.0.0"}')
-        return 'done'
-      }),
-    ).rejects.toThrow('plugin files missing after operation')
-
-    expect(fs.existsSync(extensionDir)).toBe(true)
-    expect(fs.existsSync(path.join(extensionDir, SENTINEL))).toBe(true)
-  })
-
-  test('first-time install (no existing dir): staging works without backup', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
-    fs.mkdirSync(path.join(tmpDir, 'extensions'), {recursive: true})
-
-    const result = await withPluginBackup(api, PLUGIN_ID, async ({stagingDir}) => {
-      expect(fs.existsSync(extensionDir)).toBe(false)
-      simulateStagedInstall(stagingDir!, PLUGIN_ID, '1.0.0')
-      return 'first install'
-    })
-
-    expect(result).toBe('first install')
-    expect(fs.existsSync(path.join(extensionDir, SENTINEL))).toBe(true)
-  })
-
-  test('first-time install failure: no leftover dirs', async () => {
-    const api = makeApi(tmpDir)
-    fs.mkdirSync(path.join(tmpDir, 'extensions'), {recursive: true})
-
-    await expect(
-      withPluginBackup(api, PLUGIN_ID, async () => {
-        throw new Error('install failed')
-      }),
-    ).rejects.toThrow('install failed')
-
-    const extensionDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
-    expect(fs.existsSync(extensionDir)).toBe(false)
-    const remainingStaging = fs
-      .readdirSync(path.join(tmpDir, 'extensions'))
-      .filter((f) => f.startsWith(STAGING_DIR_PREFIX))
-    expect(remainingStaging).toHaveLength(0)
-  })
-
-  test('staging dir is on same filesystem as extensions/', async () => {
-    const api = makeApi(tmpDir)
-    setupPluginDir(tmpDir)
-    const extensionsBase = path.join(tmpDir, 'extensions')
-
-    await withPluginBackup(api, PLUGIN_ID, async ({stagingDir}) => {
-      // Verify staging dir is a sibling inside extensions/
-      expect(path.dirname(stagingDir!)).toBe(extensionsBase)
-      simulateStagedInstall(stagingDir!, PLUGIN_ID, '2.0.0')
-      return 'ok'
-    })
-  })
-})
-
-describe('withPluginBackup (in-place mode — staging: false)', () => {
-  test('preserves original dir for in-place update', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-    const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-
-    const result = await withPluginBackup(
-      api,
-      PLUGIN_ID,
-      async () => {
-        // Original dir should still exist (copied, not renamed)
-        expect(fs.existsSync(extensionDir)).toBe(true)
-        expect(fs.existsSync(backupDir)).toBe(true)
-        // Simulate in-place update
-        fs.writeFileSync(path.join(extensionDir, 'package.json'), '{"version":"2.0.0"}')
-        return 'updated'
-      },
-      {staging: false},
-    )
-
-    expect(result).toBe('updated')
-    expect(fs.existsSync(backupDir)).toBe(false)
-    expect(
-      JSON.parse(fs.readFileSync(path.join(extensionDir, 'package.json'), 'utf-8')).version,
-    ).toBe('2.0.0')
-  })
-
-  test('first install failure: cleans up partial extensionDir', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
-    fs.mkdirSync(path.join(tmpDir, 'extensions'), {recursive: true})
-
-    await expect(
-      withPluginBackup(
-        api,
-        PLUGIN_ID,
-        async () => {
-          // Simulate partial install — dir created but operation fails
-          fs.mkdirSync(extensionDir, {recursive: true})
-          fs.writeFileSync(path.join(extensionDir, 'package.json'), '{"version":"1.0.0"}')
-          throw new Error('install failed')
-        },
-        {staging: false},
-      ),
-    ).rejects.toThrow('install failed')
-
-    // Partial dir should be cleaned up
-    expect(fs.existsSync(extensionDir)).toBe(false)
-  })
-
-  test('rollback on success-without-sentinel', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-    const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-
-    await expect(
-      withPluginBackup(
-        api,
-        PLUGIN_ID,
-        async () => {
-          // Operation succeeds but removes sentinel
-          fs.unlinkSync(path.join(extensionDir, SENTINEL))
-          return 'done'
-        },
-        {staging: false},
-      ),
-    ).rejects.toThrow('plugin files missing after operation')
-
-    // Should be rolled back to original (backup had sentinel)
-    expect(fs.existsSync(path.join(extensionDir, SENTINEL))).toBe(true)
-    expect(fs.existsSync(backupDir)).toBe(false)
-  })
-
-  test('rollback restores original on failure', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-
-    await expect(
-      withPluginBackup(
-        api,
-        PLUGIN_ID,
-        async () => {
-          // Corrupt the dir
-          fs.unlinkSync(path.join(extensionDir, SENTINEL))
-          throw new Error('update failed')
-        },
-        {staging: false},
-      ),
-    ).rejects.toThrow('update failed')
-
-    // Should be rolled back to original
-    expect(fs.existsSync(path.join(extensionDir, SENTINEL))).toBe(true)
-    expect(
-      JSON.parse(fs.readFileSync(path.join(extensionDir, 'package.json'), 'utf-8')).version,
-    ).toBe('1.0.0')
-  })
-})
-
-describe('withPluginBackup (no stateDir)', () => {
-  test('passes through to operation', async () => {
-    const api = makeApi(tmpDir)
-    ;(api.runtime.state as any).resolveStateDir = () => ''
-
-    const result = await withPluginBackup(api, PLUGIN_ID, async () => 'passthrough')
-    expect(result).toBe('passthrough')
-  })
-})
-
-describe('recoverOrphanedBackup', () => {
-  test('recovers from orphaned backup dir when plugin dir is missing', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
-    const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-
-    // Create orphaned backup (as if update was interrupted)
-    fs.mkdirSync(backupDir, {recursive: true})
-    fs.writeFileSync(path.join(backupDir, SENTINEL), '{}')
-    fs.writeFileSync(path.join(backupDir, 'package.json'), '{"version":"1.0.0"}')
-
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-
-    expect(fs.existsSync(extensionDir)).toBe(true)
-    expect(fs.existsSync(path.join(extensionDir, SENTINEL))).toBe(true)
-    expect(fs.existsSync(backupDir)).toBe(false)
-  })
-
-  test('warns when recovered dir is missing sentinel', async () => {
-    const api = makeApi(tmpDir) as PluginApi & {_logs: string[]}
-    const extensionDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
-    const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-
-    // Create orphaned backup without sentinel
-    fs.mkdirSync(backupDir, {recursive: true})
-    fs.writeFileSync(path.join(backupDir, 'package.json'), '{"version":"1.0.0"}')
-
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-
-    expect(fs.existsSync(extensionDir)).toBe(true)
-    expect(fs.existsSync(backupDir)).toBe(false)
-    expect(api._logs.some((l: string) => l.includes('missing sentinel'))).toBe(true)
-  })
-
-  test('cleans up stale backup when plugin dir is healthy', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-    const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-
-    // Create stale backup alongside healthy plugin
-    fs.mkdirSync(backupDir, {recursive: true})
-    fs.writeFileSync(path.join(backupDir, SENTINEL), '{}')
-
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-
-    expect(fs.existsSync(extensionDir)).toBe(true)
-    expect(fs.existsSync(backupDir)).toBe(false)
-  })
-
-  test('cleans up stale legacy zip when plugin dir is healthy', async () => {
-    const api = makeApi(tmpDir)
-    const extensionDir = setupPluginDir(tmpDir)
-    const legacyZip = `${extensionDir}${LEGACY_BACKUP_ZIP_SUFFIX}`
-
-    fs.writeFileSync(legacyZip, 'fake-zip-data')
-
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-
-    expect(fs.existsSync(extensionDir)).toBe(true)
-    expect(fs.existsSync(legacyZip)).toBe(false)
-  })
-
-  test('no-op when no backups and plugin is healthy', async () => {
-    const api = makeApi(tmpDir) as PluginApi & {_logs: string[]}
-    setupPluginDir(tmpDir)
-
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-
-    // No recovery logs
-    expect((api as any)._logs.filter((l: string) => l.includes('recover'))).toHaveLength(0)
-  })
-
-  test('no-op when plugin dir missing and no backups exist', async () => {
-    const api = makeApi(tmpDir)
-    fs.mkdirSync(path.join(tmpDir, 'extensions'), {recursive: true})
-
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-
-    const extensionDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
-    expect(fs.existsSync(extensionDir)).toBe(false)
-  })
-
-  test('cleans orphaned staging dirs at startup', async () => {
-    const api = makeApi(tmpDir)
-    setupPluginDir(tmpDir)
-    const extensionsBase = path.join(tmpDir, 'extensions')
-
-    // Create orphaned staging dirs
-    const staging1 = path.join(extensionsBase, `${STAGING_DIR_PREFIX}${PLUGIN_ID}-aabbccdd`)
-    const staging2 = path.join(extensionsBase, `${STAGING_DIR_PREFIX}${PLUGIN_ID}-11223344`)
-    fs.mkdirSync(path.join(staging1, 'extensions', PLUGIN_ID), {recursive: true})
-    fs.writeFileSync(path.join(staging1, 'openclaw.json'), '{}')
-    fs.mkdirSync(staging2, {recursive: true})
-
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-
-    expect(fs.existsSync(staging1)).toBe(false)
-    expect(fs.existsSync(staging2)).toBe(false)
-  })
-
-  test('no-op when no stateDir', async () => {
-    const api = makeApi(tmpDir)
-    ;(api.runtime.state as any).resolveStateDir = () => ''
-
-    // Should not throw
-    await recoverOrphanedBackup(api, PLUGIN_ID)
-  })
-})
-
-describe('cleanOrphanedStagingDirs', () => {
-  test('removes staging dirs for the specified plugin only', () => {
-    const api = makeApi(tmpDir)
-    const extensionsBase = path.join(tmpDir, 'extensions')
-    fs.mkdirSync(extensionsBase, {recursive: true})
-
-    // Create staging dirs for our plugin and another plugin
-    const ours = path.join(extensionsBase, `${STAGING_DIR_PREFIX}${PLUGIN_ID}-aabb1122`)
-    const other = path.join(extensionsBase, `${STAGING_DIR_PREFIX}other-plugin-ccdd3344`)
-    fs.mkdirSync(ours, {recursive: true})
-    fs.mkdirSync(other, {recursive: true})
-
-    cleanOrphanedStagingDirs(api, PLUGIN_ID)
-
-    expect(fs.existsSync(ours)).toBe(false)
-    expect(fs.existsSync(other)).toBe(true)
-  })
-
-  test('does not delete staging dirs of plugin whose ID is a superstring', () => {
-    const api = makeApi(tmpDir)
-    const extensionsBase = path.join(tmpDir, 'extensions')
-    fs.mkdirSync(extensionsBase, {recursive: true})
-
-    // "test-plugin" should NOT match "test-plugin-extra"
-    const ours = path.join(extensionsBase, `${STAGING_DIR_PREFIX}${PLUGIN_ID}-aabb1122`)
-    const longerPlugin = path.join(
-      extensionsBase,
-      `${STAGING_DIR_PREFIX}${PLUGIN_ID}-extra-ccdd3344`,
-    )
-    fs.mkdirSync(ours, {recursive: true})
-    fs.mkdirSync(longerPlugin, {recursive: true})
-
-    cleanOrphanedStagingDirs(api, PLUGIN_ID)
-
-    expect(fs.existsSync(ours)).toBe(false)
-    // longer plugin name must survive — it's a different plugin
-    expect(fs.existsSync(longerPlugin)).toBe(true)
-  })
-
-  test('staging install cleans previous orphaned staging dirs', async () => {
-    const api = makeApi(tmpDir)
-    setupPluginDir(tmpDir)
-    const extensionsBase = path.join(tmpDir, 'extensions')
-
-    // Create an orphaned staging dir from a previous interrupted attempt
-    const orphaned = path.join(extensionsBase, `${STAGING_DIR_PREFIX}${PLUGIN_ID}-deadbeef`)
-    fs.mkdirSync(path.join(orphaned, 'extensions', PLUGIN_ID), {recursive: true})
-    fs.writeFileSync(path.join(orphaned, 'openclaw.json'), '{}')
-
-    await withPluginBackup(api, PLUGIN_ID, async ({stagingDir}) => {
-      // Orphaned dir should already be cleaned up
-      expect(fs.existsSync(orphaned)).toBe(false)
-      // But our new staging dir should exist
-      expect(fs.existsSync(stagingDir!)).toBe(true)
-      simulateStagedInstall(stagingDir!, PLUGIN_ID, '2.0.0')
-      return 'ok'
-    })
-
-    // No staging dirs left
-    const remaining = fs.readdirSync(extensionsBase).filter((f) => f.startsWith(STAGING_DIR_PREFIX))
-    expect(remaining).toHaveLength(0)
-  })
-})