@chrysb/alphaclaw 0.8.7-beta.1 → 0.8.7-beta.3

package/bin/alphaclaw.js

@@ -16,6 +16,11 @@ const {
 const {
   applyPendingAlphaclawUpdate,
 } = require("../lib/server/pending-alphaclaw-update");
+const {
+  getManagedAlphaclawCliPath,
+  getManagedAlphaclawRuntimeDir,
+  syncManagedAlphaclawRuntimeWithBundled,
+} = require("../lib/server/alphaclaw-runtime");
 const {
   applyPendingOpenclawUpdate,
 } = require("../lib/server/pending-openclaw-update");
@@ -24,14 +29,10 @@ const {
   prependManagedOpenclawBinToPath,
   syncManagedOpenclawRuntimeWithBundled,
 } = require("../lib/server/openclaw-runtime");
-
-const kUsageTrackerPluginPath = path.resolve(
-  __dirname,
-  "..",
-  "lib",
-  "plugin",
-  "usage-tracker",
-);
+const {
+  ensurePluginsShell,
+  ensureUsageTrackerPluginEntry,
+} = require("../lib/server/usage-tracker-config");
 
 // ---------------------------------------------------------------------------
 // Parse CLI flags
@@ -173,10 +174,89 @@ if (portFlag) {
   process.env.PORT = portFlag;
 }
 
+const kManagedAlphaclawRuntimeEnvFlag = "ALPHACLAW_MANAGED_RUNTIME_ACTIVE";
+const shouldBootstrapManagedAlphaclawRuntime =
+  command === "start" &&
+  process.env[kManagedAlphaclawRuntimeEnvFlag] !== "1";
+
 // ---------------------------------------------------------------------------
 // 2. Create directory structure
 // ---------------------------------------------------------------------------
 
+if (shouldBootstrapManagedAlphaclawRuntime) {
+  const { spawn } = require("child_process");
+  const managedAlphaclawRuntimeDir = getManagedAlphaclawRuntimeDir({ rootDir });
+  const pendingUpdateMarker = path.join(rootDir, ".alphaclaw-update-pending");
+  if (fs.existsSync(pendingUpdateMarker)) {
+    applyPendingAlphaclawUpdate({
+      execSyncImpl: execSync,
+      fsModule: fs,
+      installDir: managedAlphaclawRuntimeDir,
+      logger: console,
+      markerPath: pendingUpdateMarker,
+    });
+  }
+  try {
+    syncManagedAlphaclawRuntimeWithBundled({
+      execSyncImpl: execSync,
+      fsModule: fs,
+      logger: console,
+      runtimeDir: managedAlphaclawRuntimeDir,
+    });
+  } catch (error) {
+    console.log(
+      `[alphaclaw] Could not sync managed AlphaClaw runtime from bundled install: ${error.message}`,
+    );
+  }
+
+  const managedAlphaclawCliPath = getManagedAlphaclawCliPath({
+    runtimeDir: managedAlphaclawRuntimeDir,
+  });
+  if (!fs.existsSync(managedAlphaclawCliPath)) {
+    console.error(
+      `[alphaclaw] Managed AlphaClaw runtime missing CLI at ${managedAlphaclawCliPath}`,
+    );
+    process.exit(1);
+  }
+
+  const runtimeChild = spawn(
+    process.argv[0],
+    [managedAlphaclawCliPath, ...process.argv.slice(2)],
+    {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        [kManagedAlphaclawRuntimeEnvFlag]: "1",
+        ALPHACLAW_BOOTSTRAP_CLI_PATH: __filename,
+      },
+    },
+  );
+
+  const forwardSignal = (signal) => {
+    if (runtimeChild.exitCode === null && !runtimeChild.killed) {
+      runtimeChild.kill(signal);
+    }
+  };
+
+  process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+  process.on("SIGINT", () => forwardSignal("SIGINT"));
+
+  runtimeChild.on("error", (error) => {
+    console.error(
+      `[alphaclaw] Managed AlphaClaw runtime launch failed: ${error.message}`,
+    );
+    process.exit(1);
+  });
+
+  runtimeChild.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(Number.isInteger(code) ? code : 0);
+  });
+} else {
+
 const openclawDir = path.join(rootDir, ".openclaw");
 fs.mkdirSync(openclawDir, { recursive: true });
 const { hourlyGitSyncPath } = migrateManagedInternalFiles({
@@ -210,36 +290,6 @@ if (fs.existsSync(pendingUpdateMarker)) {
   }
 }
 
-const pendingOpenclawUpdateMarker = path.join(rootDir, ".openclaw-update-pending");
-const managedOpenclawRuntimeDir = getManagedOpenclawRuntimeDir({ rootDir });
-if (fs.existsSync(pendingOpenclawUpdateMarker)) {
-  applyPendingOpenclawUpdate({
-    execSyncImpl: execSync,
-    fsModule: fs,
-    installDir: managedOpenclawRuntimeDir,
-    logger: console,
-    markerPath: pendingOpenclawUpdateMarker,
-  });
-}
-try {
-  syncManagedOpenclawRuntimeWithBundled({
-    execSyncImpl: execSync,
-    fsModule: fs,
-    logger: console,
-    runtimeDir: managedOpenclawRuntimeDir,
-  });
-} catch (error) {
-  console.log(
-    `[alphaclaw] Could not sync managed OpenClaw runtime from bundled install: ${error.message}`,
-  );
-}
-prependManagedOpenclawBinToPath({
-  env: process.env,
-  fsModule: fs,
-  logger: console,
-  runtimeDir: managedOpenclawRuntimeDir,
-});
-
 // ---------------------------------------------------------------------------
 // 3. Symlink ~/.openclaw -> <root>/.openclaw
 // ---------------------------------------------------------------------------
@@ -546,7 +596,41 @@ if (!kSetupPassword) {
 }
 
 // ---------------------------------------------------------------------------
-// 7. Set OPENCLAW_HOME globally so all child processes inherit it
+// 7. Prepare managed OpenClaw runtime
+// ---------------------------------------------------------------------------
+
+const pendingOpenclawUpdateMarker = path.join(rootDir, ".openclaw-update-pending");
+const managedOpenclawRuntimeDir = getManagedOpenclawRuntimeDir({ rootDir });
+if (fs.existsSync(pendingOpenclawUpdateMarker)) {
+  applyPendingOpenclawUpdate({
+    execSyncImpl: execSync,
+    fsModule: fs,
+    installDir: managedOpenclawRuntimeDir,
+    logger: console,
+    markerPath: pendingOpenclawUpdateMarker,
+  });
+}
+try {
+  syncManagedOpenclawRuntimeWithBundled({
+    execSyncImpl: execSync,
+    fsModule: fs,
+    logger: console,
+    runtimeDir: managedOpenclawRuntimeDir,
+  });
+} catch (error) {
+  console.log(
+    `[alphaclaw] Could not sync managed OpenClaw runtime from bundled install: ${error.message}`,
+  );
+}
+prependManagedOpenclawBinToPath({
+  env: process.env,
+  fsModule: fs,
+  logger: console,
+  runtimeDir: managedOpenclawRuntimeDir,
+});
+
+// ---------------------------------------------------------------------------
+// 8. Set OPENCLAW_HOME globally so all child processes inherit it
 // ---------------------------------------------------------------------------
 
 process.env.OPENCLAW_HOME = rootDir;
@@ -555,7 +639,7 @@ process.env.GOG_KEYRING_PASSWORD =
   process.env.GOG_KEYRING_PASSWORD || "alphaclaw";
 
 // ---------------------------------------------------------------------------
-// 8. Install gog (Google Workspace CLI) if not present
+// 9. Install gog (Google Workspace CLI) if not present
 // ---------------------------------------------------------------------------
 
 process.env.XDG_CONFIG_HOME = openclawDir;
@@ -588,7 +672,7 @@ if (!gogInstalled) {
 }
 
 // ---------------------------------------------------------------------------
-// 9. Install/reconcile system cron entry
+// 10. Install/reconcile system cron entry
 // ---------------------------------------------------------------------------
 
 const packagedHourlyGitSyncPath = path.join(setupDir, "hourly-git-sync.sh");
@@ -654,7 +738,7 @@ if (fs.existsSync(hourlyGitSyncPath)) {
 }
 
 // ---------------------------------------------------------------------------
-// 9. Start cron daemon if available
+// 11. Start cron daemon if available
 // ---------------------------------------------------------------------------
 
 try {
@@ -668,7 +752,7 @@ try {
 } catch {}
 
 // ---------------------------------------------------------------------------
-// 10. Reconcile channels if already onboarded
+// 12. Reconcile channels if already onboarded
 // ---------------------------------------------------------------------------
 
 const configPath = path.join(openclawDir, "openclaw.json");
@@ -816,10 +900,7 @@ if (fs.existsSync(configPath)) {
   try {
     const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
     if (!cfg.channels) cfg.channels = {};
-    if (!cfg.plugins) cfg.plugins = {};
-    if (!cfg.plugins.load) cfg.plugins.load = {};
-    if (!Array.isArray(cfg.plugins.load.paths)) cfg.plugins.load.paths = [];
-    if (!cfg.plugins.entries) cfg.plugins.entries = {};
+    ensurePluginsShell(cfg);
     let changed = false;
 
     if (process.env.TELEGRAM_BOT_TOKEN && !cfg.channels.telegram) {
@@ -845,12 +926,7 @@ if (fs.existsSync(configPath)) {
       console.log("[alphaclaw] Discord added");
       changed = true;
     }
-    if (!cfg.plugins.load.paths.includes(kUsageTrackerPluginPath)) {
-      cfg.plugins.load.paths.push(kUsageTrackerPluginPath);
-      changed = true;
-    }
-    if (cfg.plugins.entries["usage-tracker"]?.enabled !== true) {
-      cfg.plugins.entries["usage-tracker"] = { enabled: true };
+    if (ensureUsageTrackerPluginEntry(cfg)) {
       changed = true;
     }
 
@@ -952,3 +1028,4 @@ try {
 
 console.log("[alphaclaw] Setup complete -- starting server");
 require("../lib/server.js");
+}

package/lib/server/alphaclaw-runtime.js

@@ -0,0 +1,238 @@
+const fs = require("fs");
+const path = require("path");
+
+const { kRootDir } = require("./constants");
+const { compareVersionParts } = require("./helpers");
+const {
+  computePackageFingerprint,
+  isPackageRootSymlink,
+  packLocalPackageForInstall,
+} = require("./package-fingerprint");
+
+const getManagedAlphaclawRuntimeDir = ({ rootDir = kRootDir } = {}) =>
+  path.join(rootDir, ".alphaclaw-runtime");
+
+const getBundledAlphaclawPackageRoot = () => path.resolve(__dirname, "..", "..");
+
+const getManagedAlphaclawPackageRoot = ({ runtimeDir } = {}) =>
+  path.join(
+    runtimeDir || getManagedAlphaclawRuntimeDir(),
+    "node_modules",
+    "@chrysb",
+    "alphaclaw",
+  );
+
+const getManagedAlphaclawCliPath = ({ runtimeDir } = {}) =>
+  path.join(
+    getManagedAlphaclawPackageRoot({ runtimeDir }),
+    "bin",
+    "alphaclaw.js",
+  );
+
+const getManagedAlphaclawPackageJsonPath = ({ runtimeDir } = {}) =>
+  path.join(
+    getManagedAlphaclawPackageRoot({ runtimeDir }),
+    "package.json",
+  );
+
+const ensureManagedAlphaclawRuntimeProject = ({
+  fsModule = fs,
+  runtimeDir,
+} = {}) => {
+  const resolvedRuntimeDir = runtimeDir || getManagedAlphaclawRuntimeDir();
+  const packageJsonPath = path.join(resolvedRuntimeDir, "package.json");
+  fsModule.mkdirSync(resolvedRuntimeDir, { recursive: true });
+  if (!fsModule.existsSync(packageJsonPath)) {
+    fsModule.writeFileSync(
+      packageJsonPath,
+      JSON.stringify(
+        {
+          name: "alphaclaw-runtime",
+          private: true,
+        },
+        null,
+        2,
+      ),
+    );
+  }
+  return {
+    runtimeDir: resolvedRuntimeDir,
+    packageJsonPath,
+  };
+};
+
+const readManagedAlphaclawRuntimeVersion = ({
+  fsModule = fs,
+  runtimeDir,
+} = {}) => {
+  try {
+    const pkg = JSON.parse(
+      fsModule.readFileSync(
+        getManagedAlphaclawPackageJsonPath({ runtimeDir }),
+        "utf8",
+      ),
+    );
+    return String(pkg?.version || "").trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+const readBundledAlphaclawVersion = ({
+  fsModule = fs,
+  packageJsonPath = path.resolve(__dirname, "..", "..", "package.json"),
+} = {}) => {
+  try {
+    const pkg = JSON.parse(fsModule.readFileSync(packageJsonPath, "utf8"));
+    return String(pkg?.version || "").trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+const shellQuote = (value) =>
+  `'${String(value || "").replace(/'/g, `'\"'\"'`)}'`;
+
+const installManagedAlphaclawRuntime = ({
+  execSyncImpl,
+  fsModule = fs,
+  runtimeDir,
+  spec,
+  sourcePath,
+} = {}) => {
+  const normalizedSourcePath = String(sourcePath || "").trim();
+  const normalizedSpec = normalizedSourcePath
+    ? normalizedSourcePath
+    : String(spec || "").trim() || "@chrysb/alphaclaw@latest";
+  ensureManagedAlphaclawRuntimeProject({
+    fsModule,
+    runtimeDir,
+  });
+  let packedSource = null;
+  try {
+    const installTarget = normalizedSourcePath
+      ? (() => {
+          packedSource = packLocalPackageForInstall({
+            execSyncImpl,
+            fsModule,
+            packageRoot: normalizedSourcePath,
+            tempDirPrefix: "alphaclaw-runtime-pack-",
+          });
+          return packedSource.tarballPath;
+        })()
+      : normalizedSpec;
+    execSyncImpl(
+      `npm install ${shellQuote(installTarget)} --omit=dev --no-save --save=false --package-lock=false --prefer-online`,
+      {
+        cwd: runtimeDir,
+        stdio: "inherit",
+        timeout: 180000,
+      },
+    );
+  } finally {
+    packedSource?.cleanup?.();
+  }
+  return {
+    spec: normalizedSpec,
+    version: readManagedAlphaclawRuntimeVersion({
+      fsModule,
+      runtimeDir,
+    }),
+  };
+};
+
+const syncManagedAlphaclawRuntimeWithBundled = ({
+  execSyncImpl,
+  fsModule = fs,
+  logger = console,
+  runtimeDir,
+  packageRoot = getBundledAlphaclawPackageRoot(),
+  packageJsonPath,
+} = {}) => {
+  const bundledVersion = readBundledAlphaclawVersion({
+    fsModule,
+    packageJsonPath: packageJsonPath || path.join(packageRoot, "package.json"),
+  });
+  if (!bundledVersion) {
+    return {
+      checked: false,
+      synced: false,
+      bundledVersion: null,
+      runtimeVersion: readManagedAlphaclawRuntimeVersion({
+        fsModule,
+        runtimeDir,
+      }),
+    };
+  }
+
+  const runtimeVersion = readManagedAlphaclawRuntimeVersion({
+    fsModule,
+    runtimeDir,
+  });
+  const runtimePackageRoot = getManagedAlphaclawPackageRoot({ runtimeDir });
+  const runtimePackageRootIsSymlink = isPackageRootSymlink({
+    fsModule,
+    packageRoot: runtimePackageRoot,
+  });
+  const bundledFingerprint = computePackageFingerprint({
+    fsModule,
+    packageRoot,
+    packageJsonPath: packageJsonPath || path.join(packageRoot, "package.json"),
+  });
+  const runtimeFingerprint = computePackageFingerprint({
+    fsModule,
+    packageRoot: runtimePackageRoot,
+    packageJsonPath: getManagedAlphaclawPackageJsonPath({ runtimeDir }),
+  });
+  if (runtimeVersion && compareVersionParts(runtimeVersion, bundledVersion) >= 0) {
+    if (
+      compareVersionParts(runtimeVersion, bundledVersion) > 0 ||
+      (!runtimePackageRootIsSymlink &&
+        (!bundledFingerprint || runtimeFingerprint === bundledFingerprint))
+    ) {
+      return {
+        checked: true,
+        synced: false,
+        bundledVersion,
+        runtimeVersion,
+      };
+    }
+    logger.log(
+      runtimePackageRootIsSymlink
+        ? `[alphaclaw] Managed AlphaClaw runtime ${runtimeVersion} is symlinked to the bundled package; refreshing runtime...`
+        : `[alphaclaw] Managed AlphaClaw runtime ${runtimeVersion} differs from bundled ${bundledVersion}; refreshing runtime...`,
+    );
+  } else {
+    logger.log(
+      runtimeVersion
+        ? `[alphaclaw] Managed AlphaClaw runtime ${runtimeVersion} is older than bundled ${bundledVersion}; syncing runtime...`
+        : `[alphaclaw] Managed AlphaClaw runtime missing; seeding bundled AlphaClaw ${bundledVersion}...`,
+    );
+  }
+
+  const installResult = installManagedAlphaclawRuntime({
+    execSyncImpl,
+    fsModule,
+    runtimeDir,
+    sourcePath: packageRoot,
+  });
+  return {
+    checked: true,
+    synced: true,
+    bundledVersion,
+    runtimeVersion: installResult.version || bundledVersion,
+  };
+};
+
+module.exports = {
+  ensureManagedAlphaclawRuntimeProject,
+  getBundledAlphaclawPackageRoot,
+  getManagedAlphaclawCliPath,
+  getManagedAlphaclawPackageJsonPath,
+  getManagedAlphaclawPackageRoot,
+  getManagedAlphaclawRuntimeDir,
+  installManagedAlphaclawRuntime,
+  readBundledAlphaclawVersion,
+  readManagedAlphaclawRuntimeVersion,
+  syncManagedAlphaclawRuntimeWithBundled,
+};

package/lib/server/alphaclaw-version.js

@@ -126,9 +126,15 @@ const createAlphaclawVersionService = () => {
     // On bare metal / Mac / Linux, spawn a replacement process then exit.
     console.log("[alphaclaw] Spawning new process and exiting...");
     const { spawn } = require("child_process");
-    const child = spawn(process.argv[0], process.argv.slice(1), {
+    const nextEnv = { ...process.env };
+    delete nextEnv.ALPHACLAW_MANAGED_RUNTIME_ACTIVE;
+    const bootstrapCliPath =
+      String(process.env.ALPHACLAW_BOOTSTRAP_CLI_PATH || "").trim() ||
+      process.argv[1];
+    const child = spawn(process.argv[0], [bootstrapCliPath, ...process.argv.slice(2)], {
       detached: true,
       stdio: "inherit",
+      env: nextEnv,
     });
     child.unref();
     process.exit(0);

package/lib/server/openclaw-runtime.js

@@ -6,10 +6,32 @@ const {
   compareVersionParts,
   normalizeOpenclawVersion,
 } = require("./helpers");
+const {
+  computePackageFingerprint,
+  isPackageRootSymlink,
+  packLocalPackageForInstall,
+  resolvePackageRootFromEntryPath,
+} = require("./package-fingerprint");
 
 const getManagedOpenclawRuntimeDir = ({ rootDir = kRootDir } = {}) =>
   path.join(rootDir, ".openclaw-runtime");
 
+const getBundledOpenclawPackageRoot = ({
+  fsModule = fs,
+  resolveImpl = require.resolve,
+} = {}) =>
+  resolvePackageRootFromEntryPath({
+    fsModule,
+    entryPath: resolveImpl("openclaw"),
+  });
+
+const getManagedOpenclawPackageRoot = ({ runtimeDir } = {}) =>
+  path.join(
+    runtimeDir || getManagedOpenclawRuntimeDir(),
+    "node_modules",
+    "openclaw",
+  );
+
 const getManagedOpenclawBinDir = ({ runtimeDir } = {}) =>
   path.join(
     runtimeDir || getManagedOpenclawRuntimeDir(),
@@ -22,9 +44,7 @@ const getManagedOpenclawBinPath = ({ runtimeDir } = {}) =>
 
 const getManagedOpenclawPackageJsonPath = ({ runtimeDir } = {}) =>
   path.join(
-    runtimeDir || getManagedOpenclawRuntimeDir(),
-    "node_modules",
-    "openclaw",
+    getManagedOpenclawPackageRoot({ runtimeDir }),
     "package.json",
   );
 
@@ -76,8 +96,14 @@ const readBundledOpenclawVersion = ({
   resolveImpl = require.resolve,
 } = {}) => {
   try {
-    const pkgPath = resolveImpl("openclaw/package.json");
-    const pkg = JSON.parse(fsModule.readFileSync(pkgPath, "utf8"));
+    const packageRoot = getBundledOpenclawPackageRoot({
+      fsModule,
+      resolveImpl,
+    });
+    if (!packageRoot) return null;
+    const pkg = JSON.parse(
+      fsModule.readFileSync(path.join(packageRoot, "package.json"), "utf8"),
+    );
     return normalizeOpenclawVersion(pkg?.version || "");
   } catch {
     return null;
@@ -136,21 +162,41 @@ const installManagedOpenclawRuntime = ({
   logger = console,
   runtimeDir,
   spec,
+  sourcePath,
   alphaclawRoot,
 } = {}) => {
-  const normalizedSpec = String(spec || "").trim() || "openclaw@latest";
+  const normalizedSourcePath = String(sourcePath || "").trim();
+  const normalizedSpec = normalizedSourcePath
+    ? normalizedSourcePath
+    : String(spec || "").trim() || "openclaw@latest";
   ensureManagedOpenclawRuntimeProject({
     fsModule,
     runtimeDir,
   });
-  execSyncImpl(
-    `npm install ${shellQuote(normalizedSpec)} --omit=dev --no-save --save=false --package-lock=false --prefer-online`,
-    {
-      cwd: runtimeDir,
-      stdio: "inherit",
-      timeout: 180000,
-    },
-  );
+  let packedSource = null;
+  try {
+    const installTarget = normalizedSourcePath
+      ? (() => {
+          packedSource = packLocalPackageForInstall({
+            execSyncImpl,
+            fsModule,
+            packageRoot: normalizedSourcePath,
+            tempDirPrefix: "openclaw-runtime-pack-",
+          });
+          return packedSource.tarballPath;
+        })()
+      : normalizedSpec;
+    execSyncImpl(
+      `npm install ${shellQuote(installTarget)} --omit=dev --no-save --save=false --package-lock=false --prefer-online`,
+      {
+        cwd: runtimeDir,
+        stdio: "inherit",
+        timeout: 180000,
+      },
+    );
+  } finally {
+    packedSource?.cleanup?.();
+  }
   const installedVersion = readManagedOpenclawRuntimeVersion({
     fsModule,
     runtimeDir,
@@ -177,6 +223,10 @@ const syncManagedOpenclawRuntimeWithBundled = ({
   resolveImpl,
   alphaclawRoot,
 } = {}) => {
+  const bundledPackageRoot = getBundledOpenclawPackageRoot({
+    fsModule,
+    resolveImpl,
+  });
   const bundledVersion = readBundledOpenclawVersion({
     fsModule,
     resolveImpl,
@@ -194,26 +244,52 @@ const syncManagedOpenclawRuntimeWithBundled = ({
     fsModule,
     runtimeDir,
   });
+  const runtimePackageRoot = getManagedOpenclawPackageRoot({ runtimeDir });
+  const runtimePackageRootIsSymlink = isPackageRootSymlink({
+    fsModule,
+    packageRoot: runtimePackageRoot,
+  });
+  const bundledFingerprint = computePackageFingerprint({
+    fsModule,
+    packageRoot: bundledPackageRoot,
+  });
+  const runtimeFingerprint = computePackageFingerprint({
+    fsModule,
+    packageRoot: runtimePackageRoot,
+    packageJsonPath: getManagedOpenclawPackageJsonPath({ runtimeDir }),
+  });
   if (runtimeVersion && compareVersionParts(runtimeVersion, bundledVersion) >= 0) {
-    return {
-      checked: true,
-      synced: false,
-      bundledVersion,
-      runtimeVersion,
-    };
+    if (
+      compareVersionParts(runtimeVersion, bundledVersion) > 0 ||
+      (!runtimePackageRootIsSymlink &&
+        (!bundledFingerprint || runtimeFingerprint === bundledFingerprint))
+    ) {
+      return {
+        checked: true,
+        synced: false,
+        bundledVersion,
+        runtimeVersion,
+      };
+    }
+    logger.log(
+      runtimePackageRootIsSymlink
+        ? `[alphaclaw] Managed OpenClaw runtime ${runtimeVersion} is symlinked to the bundled package; refreshing runtime...`
+        : `[alphaclaw] Managed OpenClaw runtime ${runtimeVersion} differs from bundled ${bundledVersion}; refreshing runtime...`,
+    );
+  } else {
+    logger.log(
+      runtimeVersion
+        ? `[alphaclaw] Managed OpenClaw runtime ${runtimeVersion} is older than bundled ${bundledVersion}; syncing runtime...`
+        : `[alphaclaw] Managed OpenClaw runtime missing; seeding bundled OpenClaw ${bundledVersion}...`,
+    );
   }
 
-  logger.log(
-    runtimeVersion
-      ? `[alphaclaw] Managed OpenClaw runtime ${runtimeVersion} is older than bundled ${bundledVersion}; syncing runtime...`
-      : `[alphaclaw] Managed OpenClaw runtime missing; seeding bundled OpenClaw ${bundledVersion}...`,
-  );
   const installResult = installManagedOpenclawRuntime({
     execSyncImpl,
     fsModule,
     logger,
     runtimeDir,
-    spec: `openclaw@${bundledVersion}`,
+    sourcePath: bundledPackageRoot,
     alphaclawRoot,
   });
   return {
@@ -248,8 +324,10 @@ const prependManagedOpenclawBinToPath = ({
 module.exports = {
   applyManagedOpenclawPatch,
   ensureManagedOpenclawRuntimeProject,
+  getBundledOpenclawPackageRoot,
   getManagedOpenclawBinDir,
   getManagedOpenclawBinPath,
+  getManagedOpenclawPackageRoot,
   getManagedOpenclawPackageJsonPath,
   getManagedOpenclawRuntimeDir,
   installManagedOpenclawRuntime,

package/lib/server/package-fingerprint.js

@@ -0,0 +1,202 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const kIgnoredDirectoryNames = new Set([".git", "node_modules"]);
+
+const normalizeRelativePath = (packageRoot, absolutePath) =>
+  path.relative(packageRoot, absolutePath).split(path.sep).join("/");
+
+const addIncludedPath = ({ includeSet, value }) => {
+  const normalizedValue = String(value || "").trim();
+  if (!normalizedValue) return;
+  includeSet.add(normalizedValue.replace(/\/+$/, ""));
+};
+
+const collectIncludedPaths = ({ packageJson = {} } = {}) => {
+  const includeSet = new Set(["package.json"]);
+
+  if (Array.isArray(packageJson.files)) {
+    for (const entry of packageJson.files) {
+      addIncludedPath({ includeSet, value: entry });
+    }
+  }
+
+  if (typeof packageJson.bin === "string") {
+    addIncludedPath({ includeSet, value: packageJson.bin });
+  } else if (packageJson.bin && typeof packageJson.bin === "object") {
+    for (const entry of Object.values(packageJson.bin)) {
+      addIncludedPath({ includeSet, value: entry });
+    }
+  }
+
+  return Array.from(includeSet).sort((left, right) => left.localeCompare(right));
+};
+
+const walkIncludedFiles = ({
+  fsModule = fs,
+  packageRoot,
+  absolutePath,
+  files,
+}) => {
+  if (!fsModule.existsSync(absolutePath)) return;
+  const relativePath = normalizeRelativePath(packageRoot, absolutePath);
+  if (!relativePath || relativePath.startsWith("..")) return;
+
+  const stat = fsModule.lstatSync(absolutePath);
+  if (stat.isSymbolicLink()) {
+    files.push({
+      relativePath,
+      hash: `symlink:${fsModule.readlinkSync(absolutePath)}`,
+    });
+    return;
+  }
+  if (stat.isFile()) {
+    files.push({
+      relativePath,
+      hash: crypto
+        .createHash("sha256")
+        .update(fsModule.readFileSync(absolutePath))
+        .digest("hex"),
+    });
+    return;
+  }
+  if (!stat.isDirectory()) return;
+
+  const entries = fsModule
+    .readdirSync(absolutePath, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
+    if (entry.isDirectory() && kIgnoredDirectoryNames.has(entry.name)) continue;
+    walkIncludedFiles({
+      fsModule,
+      packageRoot,
+      absolutePath: path.join(absolutePath, entry.name),
+      files,
+    });
+  }
+};
+
+const computePackageFingerprint = ({
+  fsModule = fs,
+  packageRoot,
+  packageJsonPath = path.join(packageRoot, "package.json"),
+} = {}) => {
+  const resolvedPackageRoot = path.resolve(String(packageRoot || ""));
+  if (!resolvedPackageRoot || !fsModule.existsSync(packageJsonPath)) return null;
+
+  let packageJson;
+  try {
+    packageJson = JSON.parse(fsModule.readFileSync(packageJsonPath, "utf8"));
+  } catch {
+    return null;
+  }
+
+  const files = [];
+  for (const includePath of collectIncludedPaths({ packageJson })) {
+    walkIncludedFiles({
+      fsModule,
+      packageRoot: resolvedPackageRoot,
+      absolutePath: path.resolve(resolvedPackageRoot, includePath),
+      files,
+    });
+  }
+
+  const hash = crypto.createHash("sha256");
+  hash.update("package-fingerprint-v1");
+  for (const entry of files.sort((left, right) => left.relativePath.localeCompare(right.relativePath))) {
+    hash.update(entry.relativePath);
+    hash.update("\0");
+    hash.update(entry.hash);
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+};
+
+const isPackageRootSymlink = ({
+  fsModule = fs,
+  packageRoot,
+} = {}) => {
+  const resolvedPackageRoot = path.resolve(String(packageRoot || ""));
+  if (!resolvedPackageRoot || !fsModule.existsSync(resolvedPackageRoot)) return false;
+  try {
+    return fsModule.lstatSync(resolvedPackageRoot).isSymbolicLink();
+  } catch {
+    return false;
+  }
+};
+
+const resolvePackageRootFromEntryPath = ({
+  fsModule = fs,
+  entryPath,
+} = {}) => {
+  let cursor = path.dirname(path.resolve(String(entryPath || "")));
+  while (cursor && cursor !== path.dirname(cursor)) {
+    if (fsModule.existsSync(path.join(cursor, "package.json"))) {
+      return cursor;
+    }
+    cursor = path.dirname(cursor);
+  }
+  return null;
+};
+
+const packLocalPackageForInstall = ({
+  execSyncImpl,
+  fsModule = fs,
+  packageRoot,
+  tempDirPrefix = "alphaclaw-package-pack-",
+} = {}) => {
+  const resolvedPackageRoot = path.resolve(String(packageRoot || ""));
+  const packDir = fsModule.mkdtempSync(path.join(os.tmpdir(), tempDirPrefix));
+  try {
+    const packStdout = String(
+      execSyncImpl(
+        `npm pack ${shellQuote(resolvedPackageRoot)} --quiet --ignore-scripts --pack-destination ${shellQuote(packDir)}`,
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "inherit"],
+          timeout: 180000,
+        },
+      ) || "",
+    )
+      .trim()
+      .split(/\r?\n/)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    const packFileName =
+      packStdout.at(-1) ||
+      fsModule.readdirSync(packDir).find((entry) => entry.endsWith(".tgz"));
+    if (!packFileName) {
+      throw new Error(`npm pack did not produce a tarball for ${resolvedPackageRoot}`);
+    }
+    const tarballPath = path.join(packDir, packFileName);
+    if (!fsModule.existsSync(tarballPath)) {
+      throw new Error(`Packed tarball missing at ${tarballPath}`);
+    }
+    return {
+      tarballPath,
+      cleanup: () => {
+        try {
+          fsModule.rmSync(packDir, { recursive: true, force: true });
+        } catch {}
+      },
+    };
+  } catch (error) {
+    try {
+      fsModule.rmSync(packDir, { recursive: true, force: true });
+    } catch {}
+    throw error;
+  }
+};
+
+const shellQuote = (value) =>
+  `'${String(value || "").replace(/'/g, `'\"'\"'`)}'`;
+
+module.exports = {
+  computePackageFingerprint,
+  isPackageRootSymlink,
+  packLocalPackageForInstall,
+  resolvePackageRootFromEntryPath,
+};

package/lib/server/pending-alphaclaw-update.js

@@ -1,3 +1,7 @@
+const {
+  installManagedAlphaclawRuntime,
+} = require("./alphaclaw-runtime");
+
 const buildPendingAlphaclawInstallSpec = (marker = {}) => {
   const explicitSpec = String(marker?.spec || "").trim();
   if (explicitSpec) {
@@ -7,9 +11,6 @@ const buildPendingAlphaclawInstallSpec = (marker = {}) => {
   return `@chrysb/alphaclaw@${targetVersion}`;
 };
 
-const shellQuote = (value) =>
-  `'${String(value || "").replace(/'/g, `'\"'\"'`)}'`;
-
 const applyPendingAlphaclawUpdate = ({
   execSyncImpl,
   fsModule,
@@ -36,14 +37,12 @@ const applyPendingAlphaclawUpdate = ({
   logger.log(`[alphaclaw] Pending update detected, installing ${spec}...`);
 
   try {
-    execSyncImpl(
-      `npm install ${shellQuote(spec)} --omit=dev --no-save --save=false --package-lock=false --prefer-online`,
-      {
-        cwd: installDir,
-        stdio: "inherit",
-        timeout: 180000,
-      },
-    );
+    installManagedAlphaclawRuntime({
+      execSyncImpl,
+      fsModule,
+      runtimeDir: installDir,
+      spec,
+    });
     fsModule.unlinkSync(markerPath);
     logger.log("[alphaclaw] Update applied successfully");
     return {

package/lib/server/usage-tracker-config.js

@@ -8,6 +8,27 @@ const kUsageTrackerPluginPath = path.resolve(
   "usage-tracker",
 );
 
+const normalizePluginPath = (value = "") =>
+  String(value || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/\/+$/, "");
+
+const isUsageTrackerPluginPath = (value = "") => {
+  const normalizedValue = normalizePluginPath(value);
+  const normalizedCanonicalPath = normalizePluginPath(kUsageTrackerPluginPath);
+  if (!normalizedValue) return false;
+  if (
+    normalizedValue === normalizedCanonicalPath ||
+    normalizedValue.startsWith(`${normalizedCanonicalPath}/`)
+  ) {
+    return true;
+  }
+  return /(?:^|\/)(?:node_modules\/@chrysb\/alphaclaw\/lib|lib)\/plugin\/usage-tracker(?:\/.*)?$/.test(
+    normalizedValue,
+  );
+};
+
 const ensurePluginsShell = (cfg = {}) => {
   if (!cfg.plugins || typeof cfg.plugins !== "object") cfg.plugins = {};
   if (!Array.isArray(cfg.plugins.allow)) cfg.plugins.allow = [];
@@ -32,9 +53,11 @@ const ensurePluginAllowed = ({ cfg = {}, pluginKey = "" }) => {
 const ensureUsageTrackerPluginEntry = (cfg = {}) => {
   const before = JSON.stringify(cfg);
   ensurePluginAllowed({ cfg, pluginKey: "usage-tracker" });
-  if (!cfg.plugins.load.paths.includes(kUsageTrackerPluginPath)) {
-    cfg.plugins.load.paths.push(kUsageTrackerPluginPath);
-  }
+  const nextPaths = cfg.plugins.load.paths.filter(
+    (entry) => !isUsageTrackerPluginPath(entry),
+  );
+  nextPaths.push(kUsageTrackerPluginPath);
+  cfg.plugins.load.paths = nextPaths;
   cfg.plugins.entries["usage-tracker"] = {
     ...(cfg.plugins.entries["usage-tracker"] &&
     typeof cfg.plugins.entries["usage-tracker"] === "object"
@@ -64,6 +87,7 @@ const ensureUsageTrackerPluginConfig = ({ fsModule, openclawDir }) => {
 
 module.exports = {
   kUsageTrackerPluginPath,
+  isUsageTrackerPluginPath,
   ensurePluginsShell,
   ensurePluginAllowed,
   ensureUsageTrackerPluginEntry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrysb/alphaclaw",
-  "version": "0.8.7-beta.1",
+  "version": "0.8.7-beta.3",
   "publishConfig": {
     "access": "public"
   },