openclaw-node-harness 2.0.4 → 2.1.1

package/install.sh

@@ -7,6 +7,14 @@
 #   bash install.sh              # Full install
 #   bash install.sh --dry-run    # Show what would happen
 #   bash install.sh --update     # Re-copy scripts/configs, skip deps
+#
+# --dry-run behavior:
+#   Echoes every command that would execute (prefixed with [DRY-RUN]) without
+#   modifying the filesystem. Also verifies that all source paths exist —
+#   a missing source prints [DRY-RUN ERROR] so path bugs (like SCRIPT_DIR)
+#   are caught without running the install. Does NOT check destination
+#   writability (that requires actual fs calls). Exit code 0 on success,
+#   1 if any source path is missing.
 
 set -euo pipefail
 
@@ -60,10 +68,28 @@ step()  { echo -e "\n${GREEN}━━━ $* ━━━${NC}"; }
 run() {
   if $DRY_RUN; then
     echo "  [dry-run] $*"
+    # Verify source paths exist for cp/rsync commands (catches path bugs)
+    case "$1" in
+      cp)
+        if [ ! -e "$2" ]; then
+          error "[dry-run] SOURCE MISSING: $2"
+          DRY_RUN_ERRORS=$((${DRY_RUN_ERRORS:-0} + 1))
+        fi
+        ;;
+      rsync)
+        # rsync source is the last arg before the destination
+        local src="${@:(-2):1}"
+        if [ ! -e "${src%/}" ] && [ ! -d "${src%/}" ]; then
+          error "[dry-run] SOURCE MISSING: ${src}"
+          DRY_RUN_ERRORS=$((${DRY_RUN_ERRORS:-0} + 1))
+        fi
+        ;;
+    esac
   else
     "$@"
   fi
 }
+DRY_RUN_ERRORS=0
 
 detect_os() {
   case "$(uname -s)" in
@@ -536,10 +562,54 @@ fi
 run mkdir -p "$MC_DIR/data"
 
 # ============================================================
-# Step 12: ClawVault
+# Step 12: Playwright (web-fetch fallback)
+# ============================================================
+
+step "Step 12: Playwright Browser"
+
+if [ -f "$WORKSPACE/node_modules/.package-lock.json" ] && grep -q '"playwright"' "$WORKSPACE/node_modules/.package-lock.json" 2>/dev/null; then
+  info "Playwright already installed in workspace"
+else
+  info "Installing Playwright + Chromium (web-fetch fallback for anti-bot sites)..."
+  (cd "$WORKSPACE" && run npm install --save playwright 2>/dev/null) || warn "Playwright npm install failed"
+  (cd "$WORKSPACE" && run npx playwright install chromium 2>/dev/null) || warn "Chromium browser install failed"
+fi
+
+# ============================================================
+# Step 13: Companion Bridge (OpenAI-compatible Claude adapter)
 # ============================================================
 
-step "Step 12: ClawVault"
+step "Step 13: Companion Bridge"
+
+if command -v companion-bridge >/dev/null 2>&1; then
+  info "companion-bridge already installed: $(companion-bridge --version 2>/dev/null || echo 'found')"
+else
+  info "Installing companion-bridge (OpenAI-compatible adapter for Claude Code)..."
+  if [ "$OS" = "linux" ]; then
+    run sudo npm install -g companion-bridge || warn "companion-bridge install failed"
+  else
+    run npm install -g companion-bridge || warn "companion-bridge install failed"
+  fi
+fi
+
+# Deploy harness rules (user-level override for companion-bridge)
+HARNESS_SRC="${REPO_DIR}/config/harness-rules.json"
+HARNESS_DST="${HOME}/.openclaw/harness-rules.json"
+if [ -f "$HARNESS_SRC" ]; then
+  if [ ! -f "$HARNESS_DST" ]; then
+    info "Deploying default harness rules to $HARNESS_DST"
+    mkdir -p "$(dirname "$HARNESS_DST")"
+    cp "$HARNESS_SRC" "$HARNESS_DST"
+  else
+    info "Harness rules already exist at $HARNESS_DST (skipping — user-owned)"
+  fi
+fi
+
+# ============================================================
+# Step 14: ClawVault
+# ============================================================
+
+step "Step 14: ClawVault"
 
 if command -v clawvault >/dev/null 2>&1; then
   info "ClawVault already installed: $(which clawvault)"
@@ -556,10 +626,10 @@ else
 fi
 
 # ============================================================
-# Step 13: Initialize Memory
+# Step 15: Initialize Memory
 # ============================================================
 
-step "Step 13: Initialize Memory"
+step "Step 15: Initialize Memory"
 
 TODAY=$(date +%Y-%m-%d)
 DAILY_FILE="$WORKSPACE/memory/$TODAY.md"
@@ -650,10 +720,27 @@ MEM
 fi
 
 # ============================================================
-# Step 14: Install Services (role-aware, template-based)
+# Step 15.5: HyperAgent Protocol
 # ============================================================
 
-step "Step 14: Install Services (role=$NODE_ROLE)"
+step "Step 15.5: HyperAgent Protocol"
+
+if [ -f "$MESH_BIN/hyperagent.mjs" ]; then
+  mkdir -p "$HOME/.openclaw/state"
+  if node "$MESH_BIN/hyperagent.mjs" status 2>/dev/null; then
+    info "HyperAgent store initialized"
+  else
+    warn "HyperAgent init deferred (will init on first use)"
+  fi
+else
+  warn "hyperagent.mjs not found in $MESH_BIN — skipping"
+fi
+
+# ============================================================
+# Step 16: Install Services (role-aware, template-based)
+# ============================================================
+
+step "Step 16: Install Services (role=$NODE_ROLE)"
 
 MANIFEST="$REPO_DIR/services/service-manifest.json"
 LAUNCHD_TEMPLATES="$REPO_DIR/services/launchd"
@@ -683,8 +770,9 @@ else
     fi
 
     if [ "$OS" = "macos" ]; then
-      TEMPLATE="$LAUNCHD_TEMPLATES/ai.openclaw.${SVC_NAME}.plist"
-      DEST="$LAUNCHD_DEST/ai.openclaw.${SVC_NAME}.plist"
+      LAUNCHD_SVC_NAME="${SVC_NAME#openclaw-}"
+      TEMPLATE="$LAUNCHD_TEMPLATES/ai.openclaw.${LAUNCHD_SVC_NAME}.plist"
+      DEST="$LAUNCHD_DEST/ai.openclaw.${LAUNCHD_SVC_NAME}.plist"
 
       if [ ! -f "$TEMPLATE" ]; then
         warn "  Template not found: $TEMPLATE"
@@ -807,10 +895,10 @@ else
 fi
 
 # ============================================================
-# Step 15: Mesh Network (optional — if Tailscale detected)
+# Step 17: Mesh Network (optional — if Tailscale detected)
 # ============================================================
 
-step "Step 15: Mesh Network"
+step "Step 17: Mesh Network"
 
 if $SKIP_MESH; then
   info "Skipped (--skip-mesh flag set by meta-installer)"
@@ -862,6 +950,204 @@ fi
 
 fi  # end SKIP_MESH else block
 
+# ============================================================
+# Step 18: Path-Scoped Rules
+# ============================================================
+
+step "Step 18: Path-Scoped Rules"
+
+RULES_DIR="${OPENCLAW_ROOT}/rules"
+mkdir -p "$RULES_DIR"
+
+# install_rule — version-aware rule deployment.
+# Fresh install: copy. Update: compare versions. If source is newer and local
+# was modified (hash mismatch), save as .new instead of overwriting.
+install_rule() {
+  local src="$1" dst="$2" name="$3"
+  if [ ! -f "$src" ]; then return; fi
+
+  if [ ! -f "$dst" ]; then
+    cp "$src" "$dst"
+    info "Installed rule: ${name}"
+    return
+  fi
+
+  # Both exist — compare version fields
+  local src_ver dst_ver
+  src_ver=$(grep -m1 '^version:' "$src" 2>/dev/null | sed 's/version:[[:space:]]*//' || echo "0.0.0")
+  dst_ver=$(grep -m1 '^version:' "$dst" 2>/dev/null | sed 's/version:[[:space:]]*//' || echo "0.0.0")
+
+  if [ "$src_ver" = "$dst_ver" ]; then
+    return  # Same version, nothing to do
+  fi
+
+  # Different versions — check if user modified the local copy
+  local src_hash dst_hash
+  if command -v md5sum &>/dev/null; then
+    src_hash=$(md5sum "$src" | cut -d' ' -f1)
+    dst_hash=$(md5sum "$dst" | cut -d' ' -f1)
+  elif command -v md5 &>/dev/null; then
+    src_hash=$(md5 -q "$src")
+    dst_hash=$(md5 -q "$dst")
+  else
+    # Can't compare hashes — save as .new to be safe
+    cp "$src" "${dst}.new"
+    warn "Rule ${name}: new version ${src_ver} available (saved as ${name}.new)"
+    return
+  fi
+
+  if [ "$src_hash" = "$dst_hash" ]; then
+    # Same content despite different version — just update
+    cp "$src" "$dst"
+    info "Updated rule: ${name} (${dst_ver} → ${src_ver})"
+  else
+    # User-modified — don't overwrite, save as .new
+    cp "$src" "${dst}.new"
+    warn "Rule ${name}: new version ${src_ver} available but local copy modified. Saved as ${name}.new for manual merge."
+  fi
+}
+
+# Copy universal rules (always)
+for rule in security test-standards design-docs git-hygiene; do
+  install_rule "${REPO_DIR}/config/rules/universal/${rule}.md" "${RULES_DIR}/${rule}.md" "${rule}.md"
+done
+
+# Detect frameworks and install matching rules
+if [ -f "package.json" ] || [ -f "${WORKSPACE}/../../package.json" ]; then
+  PKG_FILE="package.json"
+  [ ! -f "$PKG_FILE" ] && PKG_FILE="${WORKSPACE}/../../package.json"
+
+  if [ -f "$PKG_FILE" ]; then
+    # Solidity detection
+    if grep -q '"hardhat"' "$PKG_FILE" 2>/dev/null || [ -f "hardhat.config.js" ] || [ -f "hardhat.config.ts" ] || [ -f "foundry.toml" ]; then
+      install_rule "${REPO_DIR}/config/rules/framework/solidity.md" "${RULES_DIR}/solidity.md" "solidity.md"
+      [ ! -f "${RULES_DIR}/solidity.md.new" ] || true  # install_rule handles logging
+    fi
+
+    # TypeScript detection
+    if [ -f "tsconfig.json" ] || [ -f "${WORKSPACE}/../../tsconfig.json" ]; then
+      install_rule "${REPO_DIR}/config/rules/framework/typescript.md" "${RULES_DIR}/typescript.md" "typescript.md"
+    fi
+
+    # Unity detection
+    if [ -d "ProjectSettings" ] || [ -d "Assets" ]; then
+      install_rule "${REPO_DIR}/config/rules/framework/unity.md" "${RULES_DIR}/unity.md" "unity.md"
+    fi
+  fi
+fi
+
+info "Rules directory: ${RULES_DIR} ($(ls -1 "$RULES_DIR" 2>/dev/null | wc -l | tr -d ' ') rules)"
+
+# ============================================================
+# Step 19: Plan Templates
+# ============================================================
+
+step "Step 19: Plan Templates"
+
+TEMPLATES_DIR="${OPENCLAW_ROOT}/plan-templates"
+mkdir -p "$TEMPLATES_DIR"
+
+for tmpl in team-feature team-bugfix team-deploy; do
+  TMPL_SRC="${REPO_DIR}/config/plan-templates/${tmpl}.yaml"
+  TMPL_DST="${TEMPLATES_DIR}/${tmpl}.yaml"
+  if [ -f "$TMPL_SRC" ] && [ ! -f "$TMPL_DST" ]; then
+    cp "$TMPL_SRC" "$TMPL_DST"
+    info "Installed plan template: ${tmpl}.yaml"
+  fi
+done
+
+info "Templates directory: ${TEMPLATES_DIR}"
+
+# ============================================================
+# Step 20: Claude Code Integration
+# ============================================================
+
+step "Step 20: Claude Code Integration"
+
+# Create .claude directory structure (in workspace root)
+CLAUDE_DIR="${WORKSPACE}/.claude"
+mkdir -p "${CLAUDE_DIR}/hooks"
+
+# Symlink rules directory
+RULES_LINK="${CLAUDE_DIR}/rules"
+if [ ! -L "$RULES_LINK" ] && [ ! -d "$RULES_LINK" ]; then
+  ln -s "${RULES_DIR}" "$RULES_LINK"
+  info "Symlinked .claude/rules → ${RULES_DIR}"
+fi
+
+# Deploy settings.json — merge hooks into existing if present, never overwrite permissions
+SETTINGS_SRC="${REPO_DIR}/config/claude-settings.json"
+SETTINGS_DST="${CLAUDE_DIR}/settings.json"
+if [ -f "$SETTINGS_SRC" ]; then
+  if [ ! -f "$SETTINGS_DST" ]; then
+    # Fresh install — copy wholesale
+    cp "$SETTINGS_SRC" "$SETTINGS_DST"
+    info "Deployed Claude Code settings.json"
+  elif command -v jq &>/dev/null; then
+    # Existing settings — merge hooks only, preserve user permissions
+    # Strategy: for each hook lifecycle key (SessionStart, PreToolUse, etc.),
+    # append our hook entries if they don't already exist (matched by command string)
+    MERGED=$(jq -s '
+      .[0] as $existing | .[1] as $new |
+      $existing * {
+        hooks: (
+          ($new.hooks // {}) | to_entries | reduce .[] as $entry (
+            ($existing.hooks // {});
+            .[$entry.key] as $current |
+            if $current == null then
+              . + {($entry.key): $entry.value}
+            else
+              # Append hook entries whose command is not already present
+              ($current | map(.hooks) | flatten | map(.command)) as $existing_cmds |
+              ($entry.value | map(
+                .hooks |= [.[] | select(.command as $cmd | $existing_cmds | index($cmd) | not)]
+                | select(.hooks | length > 0)
+              )) as $new_entries |
+              if ($new_entries | length) > 0 then
+                . + {($entry.key): ($current + $new_entries)}
+              else .
+              end
+            end
+          )
+        )
+      }
+    ' "$SETTINGS_DST" "$SETTINGS_SRC")
+    echo "$MERGED" > "$SETTINGS_DST"
+    info "Merged OpenClaw hooks into existing settings.json (permissions preserved)"
+  else
+    # No jq — can't safely merge. Dump patch file for manual merge.
+    cp "$SETTINGS_SRC" "${SETTINGS_DST}.openclaw-hooks"
+    warn "jq not found — hooks config saved to settings.json.openclaw-hooks for manual merge"
+  fi
+fi
+
+# Deploy hook scripts
+for hook in session-start validate-commit validate-push pre-compact session-stop log-agent; do
+  HOOK_SRC="${REPO_DIR}/.claude/hooks/${hook}.sh"
+  HOOK_DST="${CLAUDE_DIR}/hooks/${hook}.sh"
+  if [ -f "$HOOK_SRC" ]; then
+    cp "$HOOK_SRC" "$HOOK_DST"
+    chmod +x "$HOOK_DST"
+  fi
+done
+info "Deployed Claude Code hooks"
+
+# Deploy git hooks (LLM-agnostic enforcement)
+if [ -d ".git/hooks" ] || [ -d "${WORKSPACE}/../../.git/hooks" ]; then
+  GIT_HOOKS_DIR=".git/hooks"
+  [ ! -d "$GIT_HOOKS_DIR" ] && GIT_HOOKS_DIR="${WORKSPACE}/../../.git/hooks"
+
+  for ghook in pre-commit pre-push; do
+    GHOOK_SRC="${REPO_DIR}/config/git-hooks/${ghook}"
+    GHOOK_DST="${GIT_HOOKS_DIR}/${ghook}"
+    if [ -f "$GHOOK_SRC" ] && [ ! -f "$GHOOK_DST" ]; then
+      cp "$GHOOK_SRC" "$GHOOK_DST"
+      chmod +x "$GHOOK_DST"
+      info "Installed git hook: ${ghook}"
+    fi
+  done
+fi
+
 # ============================================================
 # Done!
 # ============================================================

package/lib/agent-activity.js

@@ -147,7 +147,7 @@ async function readLastEntry(filePath) {
     } else {
       const fh = await open(filePath, 'r');
       try {
-        const buffer = Buffer.allocUnsafe(chunkSize);
+        const buffer = Buffer.alloc(chunkSize);
         await fh.read(buffer, 0, chunkSize, offset);
         content = buffer.toString('utf-8');
       } finally {
@@ -195,7 +195,7 @@ async function parseJsonlTail(filePath, maxBytes = 131072) {
       const fh = await open(filePath, 'r');
       try {
         const length = size - offset;
-        const buffer = Buffer.allocUnsafe(length);
+        const buffer = Buffer.alloc(length);
         await fh.read(buffer, 0, length, offset);
         content = buffer.toString('utf-8');
       } finally {

package/lib/circling-parser.js

@@ -0,0 +1,119 @@
+/**
+ * circling-parser.js — Standalone parser for Circling Strategy LLM output.
+ *
+ * Extracted from mesh-agent.js so both production code and tests import
+ * the same module. Zero external dependencies.
+ *
+ * Handles both single-artifact and multi-artifact output formats.
+ *
+ * Single artifact: everything before ===CIRCLING_REFLECTION=== is the artifact.
+ * Multi artifact: ===CIRCLING_ARTIFACT=== / ===END_ARTIFACT=== pairs delimit
+ *   artifact content by position (content BETWEEN previous END_ARTIFACT and
+ *   next CIRCLING_ARTIFACT marker).
+ *
+ * @param {string} output — raw LLM output
+ * @param {object} [opts]
+ * @param {function} [opts.log] — optional logger (default: no-op)
+ * @param {function} [opts.legacyParser] — optional fallback parser for output
+ *   without circling delimiters. Called as legacyParser(output). Should return
+ *   { summary, confidence, vote, parse_failed }. If not provided, missing
+ *   delimiters produce parse_failed: true.
+ * @returns {{ circling_artifacts: Array<{type: string, content: string}>, summary: string, confidence: number, vote: string, parse_failed: boolean }}
+ */
+function parseCirclingReflection(output, opts = {}) {
+  const log = opts.log || (() => {});
+
+  const VALID_VOTES = new Set(['continue', 'converged', 'blocked']);
+  const result = {
+    circling_artifacts: [],
+    summary: '',
+    confidence: 0.5,
+    vote: 'continue',
+    parse_failed: false,
+  };
+
+  // Extract the reflection metadata block
+  const reflMatch = output.match(/===CIRCLING_REFLECTION===([\s\S]*?)===END_REFLECTION===/);
+  if (!reflMatch) {
+    // No circling delimiters — try legacy fallback if provided
+    if (opts.legacyParser) {
+      const legacy = opts.legacyParser(output);
+      return {
+        circling_artifacts: [],
+        summary: legacy.summary,
+        confidence: legacy.confidence,
+        vote: legacy.vote,
+        parse_failed: legacy.parse_failed,
+      };
+    }
+    return { ...result, parse_failed: true, vote: 'parse_error' };
+  }
+
+  // Parse reflection key-value pairs
+  const reflBlock = reflMatch[1];
+  const typeMatch = reflBlock.match(/^type:\s*(.+)$/m);
+  const summaryMatch = reflBlock.match(/^summary:\s*(.+)$/m);
+  const confMatch = reflBlock.match(/^confidence:\s*([\d.]+)$/m);
+  const voteMatch = reflBlock.match(/^vote:\s*(\w+)$/m);
+
+  result.summary = summaryMatch ? summaryMatch[1].trim() : '';
+  result.confidence = confMatch ? parseFloat(confMatch[1]) : 0.5;
+  const voteRaw = voteMatch ? voteMatch[1].trim().toLowerCase() : 'continue';
+  result.vote = VALID_VOTES.has(voteRaw) ? voteRaw : 'parse_error';
+  if (!VALID_VOTES.has(voteRaw)) result.parse_failed = true;
+
+  const artifactType = typeMatch ? typeMatch[1].trim() : 'unknown';
+
+  // Check for multi-artifact format
+  const artifactBlocks = [...output.matchAll(/===CIRCLING_ARTIFACT===([\s\S]*?)===END_ARTIFACT===/g)];
+
+  if (artifactBlocks.length > 0) {
+    // Multi-artifact: parse each block.
+    // Content for artifact N is between the previous ===END_ARTIFACT=== (or start
+    // of output for N=0) and this artifact's ===CIRCLING_ARTIFACT=== marker.
+    const parts = output.split('===CIRCLING_REFLECTION===')[0]; // everything before reflection
+    const artMatches = [...parts.matchAll(/===CIRCLING_ARTIFACT===\s*\n([\s\S]*?)===END_ARTIFACT===/g)];
+    const chunks = [];
+
+    for (let i = 0; i < artMatches.length; i++) {
+      const m = artMatches[i];
+      const header = m[1].trim();
+      const typeLineMatch = header.match(/^type:\s*(.+)$/m);
+      const artType = typeLineMatch ? typeLineMatch[1].trim() : `artifact_${i}`;
+
+      const artStart = m.index;
+      const prevEnd = i === 0 ? 0 : (artMatches[i - 1].index + artMatches[i - 1][0].length);
+      const content = parts.slice(prevEnd, artStart).trim();
+
+      if (content) {
+        chunks.push({ type: artType, content });
+      }
+    }
+
+    // Last chunk: content after the last END_ARTIFACT before CIRCLING_REFLECTION
+    if (artMatches.length > 0) {
+      const lastArt = artMatches[artMatches.length - 1];
+      const afterLast = parts.slice(lastArt.index + lastArt[0].length).trim();
+      if (afterLast) {
+        chunks.push({ type: 'extra', content: afterLast });
+      }
+    }
+
+    result.circling_artifacts = chunks;
+
+  } else {
+    // Single-artifact: everything before ===CIRCLING_REFLECTION=== is the artifact
+    const beforeReflection = output.split('===CIRCLING_REFLECTION===')[0].trim();
+    if (beforeReflection) {
+      result.circling_artifacts = [{ type: artifactType, content: beforeReflection }];
+    }
+  }
+
+  if (result.circling_artifacts.length === 0 && !result.parse_failed) {
+    log('CIRCLING PARSE WARNING: No artifacts extracted from output');
+  }
+
+  return result;
+}
+
+module.exports = { parseCirclingReflection };

package/lib/exec-safety.js

@@ -0,0 +1,105 @@
+/**
+ * exec-safety.js — Shared command safety filtering for mesh exec.
+ *
+ * Used by both CLI-side (mesh.js) and server-side (NATS exec handler)
+ * to block destructive or unauthorized commands before execution.
+ *
+ * Two layers:
+ *   1. DESTRUCTIVE_PATTERNS — blocklist of known-dangerous patterns
+ *   2. ALLOWED_PREFIXES — allowlist for server-side execution (opt-in)
+ */
+
+'use strict';
+
+const DESTRUCTIVE_PATTERNS = [
+  /\brm\s+(-[a-zA-Z]*)?r[a-zA-Z]*f/,      // rm -rf, rm -fr, rm --recursive --force
+  /\brm\s+(-[a-zA-Z]*)?f[a-zA-Z]*r/,       // rm -fr variants
+  /\bmkfs\b/,                                // format filesystem
+  /\bdd\s+.*of=/,                            // raw disk write
+  /\b>\s*\/dev\/[sh]d/,                      // write to raw device
+  /\bcurl\b.*\|\s*(ba)?sh/,                  // curl pipe to shell
+  /\bwget\b.*\|\s*(ba)?sh/,                  // wget pipe to shell
+  /\bchmod\s+(-[a-zA-Z]*\s+)?777\s+\//,     // chmod 777 on root paths
+  /\b:(){ :\|:& };:/,                        // fork bomb
+  /\bsudo\b/,                                // sudo escalation
+  /\bsu\s+-?\s/,                             // su user switch
+  /\bpasswd\b/,                              // password change
+  /\buseradd\b|\buserdel\b/,                 // user management
+  /\biptables\b|\bnft\b/,                    // firewall modification
+  /\bsystemctl\s+(stop|disable|mask)/,       // service disruption
+  /\blaunchctl\s+(unload|remove)/,           // macOS service disruption
+  /\bkill\s+-9\s+1\b/,                       // kill init/launchd
+  />\s*\/etc\//,                             // overwrite system config
+  /\beval\b.*\$\(/,                          // eval with command substitution
+];
+
+/**
+ * Allowed command prefixes for server-side NATS exec.
+ * Only commands starting with one of these are permitted.
+ * CLI-side uses blocklist only; server-side uses both blocklist + allowlist.
+ */
+const ALLOWED_EXEC_PREFIXES = [
+  'git ', 'npm ', 'node ', 'npx ', 'python ', 'python3 ',
+  'cat ', 'ls ', 'head ', 'tail ', 'grep ', 'find ', 'wc ',
+  'echo ', 'date ', 'uptime ', 'df ', 'free ', 'ps ',
+  'bash openclaw/', 'bash ~/openclaw/', 'bash ./bin/',
+  'cd ', 'pwd', 'which ', 'env ', 'printenv ',
+  'cargo ', 'go ', 'make ', 'pytest ', 'jest ', 'vitest ',
+];
+
+/**
+ * Check if a command matches any destructive pattern.
+ * @param {string} command
+ * @returns {{ blocked: boolean, pattern?: RegExp }}
+ */
+function checkDestructivePatterns(command) {
+  for (const pattern of DESTRUCTIVE_PATTERNS) {
+    if (pattern.test(command)) {
+      return { blocked: true, pattern };
+    }
+  }
+  return { blocked: false };
+}
+
+/**
+ * Check if a command is allowed by the server-side allowlist.
+ * @param {string} command
+ * @returns {boolean}
+ */
+function isAllowedExecCommand(command) {
+  const trimmed = (command || '').trim();
+  if (!trimmed) return false;
+  return ALLOWED_EXEC_PREFIXES.some(p => trimmed.startsWith(p));
+}
+
+/**
+ * Full server-side validation: blocklist + allowlist.
+ * Returns { allowed: true } or { allowed: false, reason: string }.
+ * @param {string} command
+ * @returns {{ allowed: boolean, reason?: string }}
+ */
+function validateExecCommand(command) {
+  const trimmed = (command || '').trim();
+  if (!trimmed) {
+    return { allowed: false, reason: 'Empty command' };
+  }
+
+  const destructive = checkDestructivePatterns(trimmed);
+  if (destructive.blocked) {
+    return { allowed: false, reason: `Blocked by destructive pattern: ${destructive.pattern}` };
+  }
+
+  if (!isAllowedExecCommand(trimmed)) {
+    return { allowed: false, reason: `Command not in server-side allowlist: ${trimmed.slice(0, 80)}` };
+  }
+
+  return { allowed: true };
+}
+
+module.exports = {
+  DESTRUCTIVE_PATTERNS,
+  ALLOWED_EXEC_PREFIXES,
+  checkDestructivePatterns,
+  isAllowedExecCommand,
+  validateExecCommand,
+};