Bug: Isolated agentTurn cron jobs fail with "Missing workspace template: AGENTS.md"

Version: 2026.3.28 (f9b1079)
OS: Windows 11 (x64)
Severity: Critical — blocks entire cron fleet

Summary

All isolated agentTurn cron jobs fail at launch with the following error before any payload runs:

Error: Missing workspace template: AGENTS.md (...\openclaw\dist\docs\reference\templates\AGENTS.md). Ensure docs/reference/templates are packaged.

Root Cause

The loadTemplate() function in workspace-CFIQ0-q3.js resolves a template directory at:

{packageRoot}/docs/reference/templates/

This directory is not included in the published npm package. The dist/ folder contains compiled JS bundles but no docs/ subdirectory, so any call to loadTemplate("AGENTS.md") throws immediately.

Impact

Every cron job using sessionTarget: "isolated" and payload.kind: "agentTurn" dies before executing. In a typical workspace this can affect 20+ scheduled jobs simultaneously, including:

• Knowledge Base Growth
• Nightly System Maintenance
• Email Triage (Yahoo)
• Hue Evening Wind Down
• GitHub Daily Digest
• Daily Blog Digest
• Gateway Heartbeat Check
• Bill Sweep, Bill Alert, Portfolio Monitor, and more

All show consecutiveErrors >= 2 within minutes of the issue appearing.

Workaround

Manually create the missing directory and placeholder files:

# Windows
New-Item -ItemType Directory -Force -Path "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates"
"# AGENTS.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\AGENTS.md"
"# BOOTSTRAP.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\BOOTSTRAP.md"

# macOS/Linux
mkdir -p "$(npm root -g)/openclaw/docs/reference/templates"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/AGENTS.md"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/BOOTSTRAP.md"

Note: This workaround is wiped on every npm install -g openclaw@latest.

Fix

The docs/reference/templates/ directory and its template files must be included in the npm package. In package.json, ensure the files array (or build output) includes this path:

{
  "files": [
    "dist/**",
    "docs/reference/templates/**"
  ]
}

Alternatively, bundle the template content directly into the compiled JS so it does not depend on filesystem path resolution at runtime.

Steps to Reproduce

1. Install [email protected] via npm install -g openclaw
2. Configure any cron job with sessionTarget: "isolated" and payload.kind: "agentTurn"
3. Trigger the job
4. Observe: job fails immediately with the "Missing workspace template" error

A PR with the fix is submitted alongside this issue.