@jiggai/recipes 0.4.50 → 0.4.51

package/README.md

@@ -53,12 +53,17 @@ It is built for people who want durable artifacts on disk, not hidden app state.
 
 ```bash
 openclaw plugins install @jiggai/recipes
+openclaw plugins enable recipes
 openclaw gateway restart
 openclaw plugins list
 ```
 
+> If you see `plugins.allow is empty; discovered non-bundled plugins may auto-load`, run `openclaw plugins enable recipes` to explicitly allowlist the plugin and suppress the warning.
+
 > **Note:** The OpenClaw plugin installer enforces `pluginApi` version checks. If you see a version mismatch error, use the npm install method below instead.
 
+> During install you may see: `Plugin "recipes" has 2 suspicious code pattern(s)`. This is expected — ClawRecipes reads API keys from your OpenClaw config and passes them to media generation scripts (e.g., DALL-E, Kling). This is required for workflow execution and is not a security concern.
+
 **npm install**
 
 ```bash
@@ -183,8 +188,28 @@ openclaw recipes workflows resume \
   --run-id <runId>
 ```
 
+### Bundled workflow examples
+
+Four ready-to-run workflow examples ship under
+[`examples/workflows/`](examples/workflows/):
+
+- [`marketing-cadence-v1`](examples/workflows/marketing-cadence-v1/) — text-only marketing cadence
+- [`marketing-image-generation-handoff`](examples/workflows/marketing-image-generation-handoff/) — image generation + handoff to social publish
+- [`marketing-video-generation-handoff`](examples/workflows/marketing-video-generation-handoff/) — video generation cadence
+- [`social-media-publish`](examples/workflows/social-media-publish/) — handoff target that publishes via kitchen-plugin-marketing + Postiz
+
+Each example directory contains the workflow JSON, a `cron-jobs.example.json`,
+an `install-crons.sh` helper, and a per-example README with prerequisites
+and install steps. See [docs/WORKFLOW_EXAMPLES_BUNDLED.md](docs/WORKFLOW_EXAMPLES_BUNDLED.md)
+for the catalog, required cron jobs, and a recommendation on
+`agents.defaults.maxConcurrent` sizing.
+
 See also:
 - [docs/WORKFLOW_RUNS_FILE_FIRST.md](docs/WORKFLOW_RUNS_FILE_FIRST.md)
+- [docs/WORKFLOW_NODES.md](docs/WORKFLOW_NODES.md)
+- [docs/WORKFLOW_APPROVALS.md](docs/WORKFLOW_APPROVALS.md)
+- [docs/WORKFLOW_EXAMPLES.md](docs/WORKFLOW_EXAMPLES.md) — small, hand-rolled pattern snippets
+- [docs/WORKFLOW_EXAMPLES_BUNDLED.md](docs/WORKFLOW_EXAMPLES_BUNDLED.md) — full bundled examples + cron/concurrency guide
 - [docs/OUTBOUND_POSTING.md](docs/OUTBOUND_POSTING.md)
 
 ---

package/docs/BUNDLED_RECIPES.md

@@ -6,6 +6,11 @@ ClawRecipes ships with bundled recipes in:
 recipes/default/
 ```
 
+> **Looking for bundled workflow examples** (not team recipes)? See
+> [`WORKFLOW_EXAMPLES_BUNDLED.md`](./WORKFLOW_EXAMPLES_BUNDLED.md) and the
+> [`examples/workflows/`](../examples/workflows/) directory for four
+> ready-to-run workflow definitions with matching cron-install scripts.
+
 You can browse them with:
 
 ```bash

package/docs/WORKFLOW_EXAMPLES.md

@@ -1,9 +1,18 @@
 # Workflow examples
 
-This document gives you copyable workflow patterns for ClawRecipes.
+This document gives you copyable workflow **patterns** for ClawRecipes —
+small snippets that illustrate individual node kinds and graph shapes.
 
-Use it together with:
+> **Looking for full, production-style workflows?**
+> See [`WORKFLOW_EXAMPLES_BUNDLED.md`](./WORKFLOW_EXAMPLES_BUNDLED.md) and
+> [`examples/workflows/`](../examples/workflows/). Those are four end-to-end
+> workflows (marketing cadence variants + social publish) complete with
+> matching cron jobs and install scripts, ready to drop into a fresh team.
+
+Use this doc together with:
 - [WORKFLOW_RUNS_FILE_FIRST.md](WORKFLOW_RUNS_FILE_FIRST.md) — concepts, node kinds, triggers, runs, edges
+- [WORKFLOW_NODES.md](WORKFLOW_NODES.md) — reference for every node type
+- [WORKFLOW_EXAMPLES_BUNDLED.md](WORKFLOW_EXAMPLES_BUNDLED.md) — full bundled examples + cron + concurrency guide
 - [OUTBOUND_POSTING.md](OUTBOUND_POSTING.md) — publishing/posting setup
 
 ---

package/docs/WORKFLOW_EXAMPLES_BUNDLED.md

@@ -0,0 +1,313 @@
+# Bundled workflow examples
+
+ClawRecipes ships four ready-to-run workflow examples under
+[`examples/workflows/`](../examples/workflows/). Each example is a copy of a
+workflow currently running in production, with all team-specific ids,
+credentials, and secrets replaced by placeholders. You can drop any of them
+into a freshly scaffolded team, install the matching crons, and run it
+end-to-end.
+
+Unlike the hand-rolled snippets in [`WORKFLOW_EXAMPLES.md`](./WORKFLOW_EXAMPLES.md),
+these are complete, multi-node, multi-agent workflows. Use this doc if you
+want to:
+
+- See what a full production cadence looks like (research → draft → QC →
+  approve → post, with optional image/video generation and social-team
+  handoff)
+- Bootstrap your own team's workflows by copying and adapting one
+- Understand the cron setup a real workflow needs
+
+## The four examples at a glance
+
+| Example | Media | Pattern | Agents used |
+|---|---|---|---|
+| [`marketing-cadence-v1`](../examples/workflows/marketing-cadence-v1/) | none | Self-posting (text only) | analyst, copywriter, compliance, lead |
+| [`marketing-image-generation-handoff`](../examples/workflows/marketing-image-generation-handoff/) | image | **Handoff** to social-team workflow | analyst, copywriter, **designer**, compliance, lead |
+| [`marketing-video-generation-handoff`](../examples/workflows/marketing-video-generation-handoff/) | video | Self-posting (see note in README) | analyst, copywriter, **designer**, compliance, lead |
+| [`social-media-publish`](../examples/workflows/social-media-publish/) | passthrough | Handoff target — publishes via kitchen-plugin-marketing + Postiz | social-team-lead |
+
+Each example directory contains:
+
+- `*.workflow.json` — the workflow definition, ready to copy into a team's
+  `shared-context/workflows/` directory
+- `cron-jobs.example.json` — the cron jobs required for the workflow, in a
+  format suitable for `openclaw cron import --from-file` bulk import
+- `install-crons.sh` — the same cron jobs as an idempotent shell script
+  using individual `openclaw cron add` calls
+- `README.md` — per-example prerequisites, install steps, gotchas, and
+  configuration points
+
+## Quick start
+
+### 1. Scaffold the teams
+
+The marketing examples expect `teamId=marketing-team`; the social example
+expects `teamId=social-team`. ClawRecipes' built-in recipes create all the
+required agents:
+
+```bash
+openclaw recipes scaffold --recipe marketing-team --team-id marketing-team
+openclaw recipes scaffold --recipe social-team     --team-id social-team
+```
+
+If you want different team ids, edit the relevant fields in the workflow
+JSON (all `*-team-*` agentId references) and set `TEAM_ID` before running
+`install-crons.sh`.
+
+### 2. Copy a workflow into the team's workspace
+
+```bash
+cp examples/workflows/marketing-image-generation-handoff/marketing-image-generation-handoff.workflow.json \
+  ~/.openclaw/workspace-marketing-team/shared-context/workflows/
+
+cp examples/workflows/social-media-publish/social-media-publish.workflow.json \
+  ~/.openclaw/workspace-social-team/shared-context/workflows/
+```
+
+### 3. Install the required crons
+
+```bash
+bash examples/workflows/marketing-image-generation-handoff/install-crons.sh
+bash examples/workflows/social-media-publish/install-crons.sh
+```
+
+Or bulk-import via JSON:
+
+```bash
+openclaw cron import --from-file examples/workflows/marketing-image-generation-handoff/cron-jobs.example.json
+openclaw cron import --from-file examples/workflows/social-media-publish/cron-jobs.example.json
+```
+
+### 4. Tune placeholders
+
+Before running, **edit the workflow JSON** to replace the placeholders left
+in the examples:
+
+- `<your-telegram-user-id>` — the `approvalTarget` in the marketing examples'
+  `meta` block and on the `approval` node
+- `<your-postiz-integration-id>` — the `integrationIds` in
+  `marketing-image-generation-handoff`'s handoff variable mapping
+
+And (for `social-media-publish`) set the gateway env vars:
+
+- `CK_BASE_URL` — a URL the gateway process can use to reach its own Kitchen
+  HTTP endpoints (e.g. `http://127.0.0.1:7777`)
+- `CK_AUTH` — `<user>:<password>` for Kitchen basic-auth
+
+### 5. Trigger a run
+
+```bash
+openclaw recipes workflows enqueue \
+  --team-id marketing-team \
+  --workflow-id marketing-image-generation-handoff
+```
+
+Or use the ClawKitchen UI: **teams → workflows → Run**.
+
+## Cron requirements
+
+Every workflow requires **two classes of crons** running periodically:
+
+### Runner-tick (1 per team)
+
+`workflow-runner-tick:<teamId>` — claims runs in `queued` status, auto-skips
+`start`/`end` nodes, and enqueues the first runnable node onto its owning
+agent's worker queue. Without this, new runs never leave `queued`.
+
+Default schedule in bundled example cron files: `*/5 * * * *` (every 5 minutes).
+Default timeout: 900 seconds.
+
+### Worker-tick (1 per agent referenced in any workflow)
+
+`workflow-worker:<teamId>:<agentId>` — drains that agent's queue and
+executes the node work. Each tick:
+
+1. Dequeues up to 5 tasks from the queue
+2. For each task: acquires a per-node lock, loads the run file, resolves
+   the node config, executes the node (`llm`, `tool`, `media-*`,
+   `human_approval`, `handoff`), writes results, and enqueues the next
+   runnable node
+
+Default schedule: `*/5 * * * *`. Default timeout: 120 seconds per session.
+
+### How many crons?
+
+Rule of thumb: **1 runner + N workers per team**, where N is the number of
+distinct `agentId` values referenced by any node across all workflows
+installed in that team. Worker crons are shared between workflows — if two
+workflows both use `marketing-team-lead`, you still only need one lead
+worker.
+
+The four bundled examples need:
+
+| Team | Workflows installed | Runners | Workers | Total |
+|---|---|---|---|---|
+| `marketing-team` | v1 only | 1 | 4 (analyst, copywriter, compliance, lead) | 5 |
+| `marketing-team` | v1 + image-handoff | 1 | 5 (+designer) | 6 |
+| `marketing-team` | v1 + image-handoff + video-handoff | 1 | 5 | 6 |
+| `social-team` | social-media-publish | 1 | 1 (lead) | 2 |
+
+## Gateway concurrency — raise `agents.defaults.maxConcurrent`
+
+> ⚠️ **This is the single most common cause of workflow runs appearing
+> "stuck"** on first install.
+
+Every workflow cron fires an isolated agent session through the gateway's
+agent system. That session invokes the `openclaw recipes workflows
+(runner|worker)-tick` CLI command via the `exec` tool, waits for it, then
+responds `NO_REPLY`. Each of those in-flight sessions counts against the
+gateway's `agents.defaults.maxConcurrent` limit.
+
+The default is:
+
+```json
+"agents": {
+  "defaults": {
+    "maxConcurrent": 8,
+    "subagents": { "maxConcurrent": 8 }
+  }
+}
+```
+
+A minimal marketing+social setup (image-handoff + social-publish) already
+runs **1 marketing-runner + 5 marketing-workers + 1 social-runner +
+1 social-worker = 8 workflow crons**. Add any memory/heartbeat crons on top
+and you are over budget. When that happens:
+
+- Crons back up into a scheduler queue and fire 15–30 minutes later than
+  intended
+- Workflow runs appear to stall mid-pipeline
+- Session failures cascade because nothing can retry while the queue is
+  saturated
+
+### Recommended setting for example-backed setups
+
+Edit `~/.openclaw/openclaw.json`:
+
+```json
+"agents": {
+  "defaults": {
+    "maxConcurrent": 24,
+    "subagents": { "maxConcurrent": 24 }
+  }
+}
+```
+
+Then restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+Adjust higher if you run many workflows or many teams. A reasonable formula:
+
+> `maxConcurrent ≥ (total workflow crons across all teams) + (other crons firing on overlapping schedules) + 4 headroom`
+
+## Model selection
+
+Bundled cron payloads **do not hard-code a model**. When the gateway runs
+a tick session, it falls back to its default model (typically configured
+under `agents.defaults.model` in `openclaw.json`).
+
+You can pin a specific model in three ways:
+
+1. **Shell install**: `MODEL=openai/gpt-5.4 bash install-crons.sh`
+
+2. **JSON import**: uncomment the `model` field in the example
+   `cron-jobs.example.json` before importing
+
+3. **After install**: `openclaw cron edit <cron-id> --model openai/gpt-5.4`
+
+Worker-tick sessions don't need smart models — they just run one
+predictable shell command and respond `NO_REPLY`. A cheap/fast model is
+ideal. Runner-ticks similarly just invoke a CLI command.
+
+### ClawKitchen default-cron model override
+
+If you use ClawKitchen's **"Install worker cron(s)"** button in the workflow
+editor instead of the bundled example files, you can set a model override
+globally via env var on the gateway:
+
+```json
+"env": {
+  "vars": {
+    "KITCHEN_WORKFLOW_CRON_MODEL": "openai/gpt-5.4"
+  }
+}
+```
+
+When set, every workflow cron that Kitchen installs will carry that
+`--model` flag. Leave unset to fall back to the gateway default.
+
+You can also override the schedule:
+
+```json
+"env": {
+  "vars": {
+    "KITCHEN_WORKFLOW_CRON_SCHEDULE": "*/10 * * * *"
+  }
+}
+```
+
+## Handoff chain
+
+`marketing-image-generation-handoff` contains a `handoff` node that targets
+`social-media-publish`. To use the handoff end-to-end:
+
+1. Install both workflows in their respective teams (`marketing-team` and
+   `social-team`)
+2. Ensure `social-media-publish`'s runtime prerequisites are satisfied
+   (kitchen-plugin-marketing installed, Postiz account configured, gateway
+   env vars set — see the example's README)
+3. Trigger a run of `marketing-image-generation-handoff`
+
+When the approval step clears, the `handoff_social_instagram` node fires
+and enqueues a new run in `social-team`. You'll see it in that team's runs
+page (or via `openclaw recipes workflows list-runs --team-id social-team`).
+
+The handoff is **fire-and-forget** by default — the marketing run completes
+without waiting for the social publish to succeed. Check the target team's
+runs page for downstream status.
+
+## Troubleshooting
+
+### Runs start but nothing happens past the first node
+Check that the **worker-tick cron for the agent owning that node** is
+installed and enabled. Each agent referenced in the workflow needs its own
+worker-tick.
+
+### Worker-tick returns `skipped_locked` on every task
+A previous worker session crashed mid-execution and left a lock file in
+`workflow-runs/<runId>/locks/<nodeId>.lock`. Locks expire after ~12 minutes.
+Either wait, or manually delete the stale lock file.
+
+### `fetch failed` during `store_and_publish` (social-media-publish)
+The gateway process can't reach its own Kitchen HTTP endpoint via the URL
+in the request's `host` header. Set `CK_BASE_URL` in the gateway env to a
+URL that IS reachable from inside the gateway process (e.g.
+`http://127.0.0.1:7777` if Kitchen binds loopback).
+
+### Runs hang at `waiting_workers` forever with no new events
+Check `openclaw cron list --json` for your workflow crons — are they
+firing? If not, the gateway cron scheduler is probably saturated. Bump
+`agents.defaults.maxConcurrent` (see the Gateway concurrency section
+above) and restart.
+
+### Node locks from crashed workers pile up duplicate queue entries
+Fixed in ClawRecipes 0.4.50+ via a `hasPendingTaskFor` guard in the
+worker-tick. If you're on an older version, upgrade.
+
+## See also
+
+- [`examples/workflows/README.md`](../examples/workflows/README.md) — top-level
+  index with install commands
+- [`WORKFLOW_RUNS_FILE_FIRST.md`](./WORKFLOW_RUNS_FILE_FIRST.md) — how the
+  runner/worker split works internally
+- [`WORKFLOW_NODES.md`](./WORKFLOW_NODES.md) — reference for all node types
+  used in these examples
+- [`WORKFLOW_APPROVALS.md`](./WORKFLOW_APPROVALS.md) — how the `human_approval`
+  node integrates with Telegram, Slack, and the web UI
+- [`MEDIA_GENERATION.md`](./MEDIA_GENERATION.md) — provider setup for
+  `media-image` / `media-video` nodes
+- [`WORKFLOW_EXAMPLES.md`](./WORKFLOW_EXAMPLES.md) — hand-rolled smaller
+  workflow examples showing individual node types

package/index.ts

@@ -46,7 +46,7 @@ import {
 import { handleScaffold, scaffoldAgentFromRecipe } from "./src/handlers/scaffold";
 import { handleAddRoleToTeam } from "./src/handlers/team-add-role";
 import { reconcileRecipeCronJobs } from "./src/handlers/cron";
-import { handleWorkflowsApprove, handleWorkflowsPollApprovals, handleWorkflowsResume, handleWorkflowsRun, handleWorkflowsRunnerOnce, handleWorkflowsRunnerTick, handleWorkflowsWorkerTick } from "./src/handlers/workflows";
+import { handleWorkflowsApprove, handleWorkflowsCleanupQueues, handleWorkflowsPollApprovals, handleWorkflowsResume, handleWorkflowsRun, handleWorkflowsRunnerOnce, handleWorkflowsRunnerTick, handleWorkflowsWorkerTick } from "./src/handlers/workflows";
 import { handleMediaDriversList } from "./src/handlers/media-drivers";
 import { listRecipeFiles, loadRecipeById, workspacePath } from "./src/lib/recipes";
 import {
@@ -750,6 +750,17 @@ workflows
             console.log(JSON.stringify(res, null, 2));
           });
 
+        workflows
+          .command("cleanup-queues")
+          .description("Remove stale queue tasks for runs that are completed, errored, or deleted")
+          .requiredOption("--team-id <teamId>", "Team id (workspace-<teamId>)")
+          .action(async (options: { teamId?: string }) => {
+            const res = await handleWorkflowsCleanupQueues(api, {
+              teamId: String(options.teamId ?? ''),
+            });
+            console.log(JSON.stringify(res, null, 2));
+          });
+
         cmd
           .command("move-ticket")
           .description("Move a ticket between backlog/in-progress/testing/done (updates Status: line)")

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "recipes",
   "name": "Recipes",
   "description": "Markdown recipes that scaffold agents and teams (workspace-local).",
-  "version": "0.4.50",
+  "version": "0.4.51",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.4.50",
+  "version": "0.4.51",
   "description": "ClawRecipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",
@@ -9,7 +9,7 @@
       "./index.ts"
     ],
     "compat": {
-      "pluginApi": "2026.4.9",
+      "pluginApi": ">=1.0.0",
       "pluginApiRange": ">=2026.3"
     },
     "build": {

package/src/handlers/workflows.ts

@@ -1,5 +1,7 @@
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import { approveWorkflowRun, enqueueWorkflowRun, pollWorkflowApprovals, resumeWorkflowRun, runWorkflowRunnerOnce, runWorkflowRunnerTick, runWorkflowWorkerTick } from '../lib/workflows/workflow-runner';
+import { cleanupQueues } from '../lib/workflows/workflow-queue';
+import { resolveTeamDir } from '../lib/workspace';
 
 export async function handleWorkflowsRun(api: OpenClawPluginApi, opts: {
   teamId: string;
@@ -79,3 +81,11 @@ export async function handleWorkflowsPollApprovals(api: OpenClawPluginApi, opts:
   if (!opts.teamId) throw new Error('--team-id is required');
   return pollWorkflowApprovals(api, { teamId: opts.teamId, limit: opts.limit });
 }
+
+export async function handleWorkflowsCleanupQueues(api: OpenClawPluginApi, opts: {
+  teamId: string;
+}) {
+  if (!opts.teamId) throw new Error('--team-id is required');
+  const teamDir = resolveTeamDir(api, opts.teamId);
+  return cleanupQueues(teamDir);
+}

package/src/lib/workflows/workflow-queue.ts

@@ -84,10 +84,58 @@ export async function enqueueTask(teamDir: string, agentId: string, task: Omit<Q
     ...task,
   };
   const p = queuePathFor(teamDir, agentId);
+
+  // If the cursor is at or beyond the current file size, the file was
+  // truncated/rotated since the cursor was written.  Reset to 0 so the
+  // worker will see this new task after it is appended.
+  const st = await loadState(teamDir, agentId);
+  let fileSize = 0;
+  try {
+    fileSize = (await fs.stat(p)).size;
+  } catch { /* file doesn't exist yet — fileSize stays 0 */ }
+  if (st.offsetBytes > 0 && st.offsetBytes >= fileSize) {
+    await writeState(teamDir, agentId, { offsetBytes: 0, updatedAt: new Date().toISOString() });
+  }
+
   await fs.appendFile(p, JSON.stringify(entry) + '\n', 'utf8');
   return { ok: true as const, path: p, task: entry };
 }
 
+/**
+ * Check whether a pending task matching {runId, nodeId} already exists in
+ * the queue past the current cursor. Used to avoid enqueueing duplicates
+ * when a re-queue would otherwise race with an in-flight tick.
+ */
+export async function hasPendingTaskFor(
+  teamDir: string,
+  agentId: string,
+  match: { runId: string; nodeId: string }
+): Promise<boolean> {
+  const qPath = queuePathFor(teamDir, agentId);
+  if (!(await fileExists(qPath))) return false;
+
+  const st = await loadState(teamDir, agentId);
+  let raw: string;
+  try {
+    raw = await fs.readFile(qPath, 'utf8');
+  } catch { // intentional: best-effort read
+    return false;
+  }
+
+  // Only consider lines at/after the cursor.
+  const tail = raw.slice(st.offsetBytes);
+  for (const line of tail.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const t = JSON.parse(line) as QueueTask;
+      if (t && t.runId === match.runId && t.nodeId === match.nodeId) return true;
+    } catch { // intentional: skip malformed queue line
+      continue;
+    }
+  }
+  return false;
+}
+
 type QueueState = {
   offsetBytes: number;
   updatedAt: string;
@@ -123,10 +171,16 @@ export async function readNextTasks(teamDir: string, agentId: string, opts?: { l
     return { ok: true as const, tasks: [] as QueueTask[], consumed: 0, message: 'Queue file not present.' };
   }
 
-  const st = await loadState(teamDir, agentId);
+  let st = await loadState(teamDir, agentId);
   const fh = await fs.open(qPath, 'r');
   try {
     const stat = await fh.stat();
+    // If the queue file was truncated/rotated, the cursor may point past EOF.
+    // Reset to 0 so we re-scan from the beginning instead of silently skipping tasks.
+    if (st.offsetBytes > stat.size) {
+      st = { offsetBytes: 0, updatedAt: new Date().toISOString() };
+      await writeState(teamDir, agentId, st);
+    }
     if (st.offsetBytes >= stat.size) {
       return { ok: true as const, tasks: [] as QueueTask[], consumed: 0, message: 'No new tasks.' };
     }
@@ -173,7 +227,7 @@ export async function dequeueNextTask(
     return { ok: true as const, task: null as DequeuedTask | null, message: 'Queue file not present.' };
   }
 
-  const st = await loadState(teamDir, agentId);
+  let st = await loadState(teamDir, agentId);
   const workerId = String(opts?.workerId ?? `worker:${process.pid}`);
   const leaseSeconds = typeof opts?.leaseSeconds === 'number' ? opts.leaseSeconds : undefined;
 
@@ -219,6 +273,12 @@ export async function dequeueNextTask(
   const fh = await fs.open(qPath, 'r');
   try {
     const stat = await fh.stat();
+    // If the queue file was truncated/rotated, the cursor may point past EOF.
+    // Reset to 0 so we re-scan from the beginning instead of silently skipping tasks.
+    if (st.offsetBytes > stat.size) {
+      st = { offsetBytes: 0, updatedAt: new Date().toISOString() };
+      await writeState(teamDir, agentId, st);
+    }
     if (st.offsetBytes < stat.size) {
       const toRead = Math.min(stat.size - st.offsetBytes, 256 * 1024);
       const buf = Buffer.alloc(toRead);
@@ -336,3 +396,77 @@ export async function compactQueue(teamDir: string, agentId: string, opts?: { mi
 
   return { ok: true as const, compacted: true, removedBytes: st.offsetBytes, remainingBytes: remaining.length };
 }
+
+const TERMINAL_STATUSES = new Set(['completed', 'error', 'canceled', 'done', 'failed']);
+
+/**
+ * Remove queue tasks whose runs no longer exist or are in a terminal state.
+ * Returns summary of what was cleaned.
+ */
+export async function cleanupQueues(teamDir: string): Promise<{
+  ok: true;
+  queuesProcessed: number;
+  tasksRemoved: number;
+  tasksKept: number;
+}> {
+  const qDir = queueDir(teamDir);
+  const runsDir = path.join(teamDir, 'shared-context', 'workflow-runs');
+
+  let files: string[];
+  try {
+    files = (await fs.readdir(qDir)).filter((f) => f.endsWith('.jsonl'));
+  } catch {
+    return { ok: true, queuesProcessed: 0, tasksRemoved: 0, tasksKept: 0 };
+  }
+
+  let totalRemoved = 0;
+  let totalKept = 0;
+
+  for (const file of files) {
+    const qPath = path.join(qDir, file);
+    let raw: string;
+    try {
+      raw = await fs.readFile(qPath, 'utf8');
+    } catch { continue; }
+
+    const lines = raw.split('\n').filter((l) => l.trim());
+    if (!lines.length) continue;
+
+    const kept: string[] = [];
+    for (const line of lines) {
+      try {
+        const task = JSON.parse(line) as QueueTask;
+        const runPath = path.join(runsDir, task.runId, 'run.json');
+
+        let remove = false;
+        try {
+          const runRaw = await fs.readFile(runPath, 'utf8');
+          const run = JSON.parse(runRaw) as { status?: string };
+          if (TERMINAL_STATUSES.has(run.status ?? '')) remove = true;
+        } catch {
+          // Run file doesn't exist — orphaned task
+          remove = true;
+        }
+
+        if (remove) {
+          totalRemoved++;
+        } else {
+          kept.push(line);
+          totalKept++;
+        }
+      } catch {
+        // Malformed line — discard
+        totalRemoved++;
+      }
+    }
+
+    if (kept.length !== lines.length) {
+      await fs.writeFile(qPath, kept.length ? kept.join('\n') + '\n' : '', 'utf8');
+      // Reset cursor state since we rewrote the file
+      const agentId = file.replace(/\.jsonl$/, '');
+      await writeState(teamDir, agentId, { offsetBytes: 0, updatedAt: new Date().toISOString() });
+    }
+  }
+
+  return { ok: true, queuesProcessed: files.length, tasksRemoved: totalRemoved, tasksKept: totalKept };
+}

package/src/lib/workflows/workflow-utils.ts

@@ -340,6 +340,10 @@ export async function loadRunFile(teamDir: string, runsDir: string, runId: strin
 export async function writeRunFile(runPath: string, fn: (cur: RunLog) => RunLog) {
   const raw = await readTextFile(runPath);
   const cur = JSON.parse(raw) as RunLog;
-  const next = fn(cur);
+  const next0 = fn(cur);
+  const next = {
+    ...next0,
+    updatedAt: new Date().toISOString(),
+  };
   await fs.writeFile(runPath, JSON.stringify(next, null, 2), 'utf8');
 }

package/src/lib/workflows/workflow-worker.ts

@@ -9,7 +9,7 @@ import { resolveTeamDir } from '../workspace';
 import { getDriver } from './media-drivers/registry';
 import { GenericDriver } from './media-drivers/generic.driver';
 import type { WorkflowLane, WorkflowNode, RunLog } from './workflow-types';
-import { dequeueNextTask, enqueueTask, releaseTaskClaim, compactQueue } from './workflow-queue';
+import { dequeueNextTask, enqueueTask, hasPendingTaskFor, releaseTaskClaim, compactQueue } from './workflow-queue';
 import { loadPriorLlmInput, loadProposedPostTextFromPriorNode } from './workflow-node-output-readers';
 import { readTextFile } from './workflow-runner-io';
 import { resolveApprovalBindingTarget } from './workflow-node-executor';
@@ -552,7 +552,17 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
     return Math.max(MIN_NODE_LOCK_TTL_MS, timeoutMs + LOCK_TTL_BUFFER_MS);
   };
 
-  for (let i = 0; i < limit; i++) {
+  // We want to process up to `limit` ACTUAL executions per tick. Stale tasks
+  // (runs that are already past the dequeued node — e.g. after a terminal
+  // run leaves dead entries in a shared agent queue) don't do any real work,
+  // so they shouldn't consume the execution budget; otherwise a backlog of
+  // stale tasks can starve in-flight runs for several ticks.
+  //
+  // Cap the total number of dequeue attempts to keep a pathological queue
+  // from turning a single tick into an unbounded scan.
+  let executedCount = 0;
+  const maxDequeues = Math.max(limit * 4, limit + 20);
+  for (let totalDequeues = 0; executedCount < limit && totalDequeues < maxDequeues; totalDequeues++) {
     const dq = await dequeueNextTask(teamDir, agentId, { workerId, leaseSeconds: 120 });
     if (!dq.ok || !dq.task) break;
 
@@ -562,6 +572,21 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
     const lockDir = path.join(runDir, 'locks');
     const lockPath = path.join(lockDir, `${task.nodeId}.lock`);
     let lockHeld = false;
+    // Tracks whether this dequeue should count against the execution budget.
+    // Defaults to true; the stale-skip path below flips it to false so stale
+    // tasks (queue entries for nodes that already advanced past success)
+    // don't starve real work from the `limit` budget.
+    //
+    // NOTE: `skipped_locked` does NOT flip this flag. Lock contention means
+    // real work is pending (just held up by another worker or a ghost lock),
+    // and the skipped_locked branch re-enqueues the task to avoid losing it.
+    // Letting lock contention escape the budget here would amplify that
+    // re-enqueue within a single tick: each dequeue past the cursor would
+    // drop a new copy at the tail (hasPendingTaskFor can't see it yet), and
+    // the loop would fabricate up to `maxDequeues` duplicates for one stuck
+    // lock. Bounding lock contention by the normal limit keeps the queue
+    // growth to O(limit) per tick.
+    let countedTowardLimit = true;
 
     try {
       if (task.kind !== 'execute_node') continue;
@@ -622,17 +647,29 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
             await fs.writeFile(lockPath, JSON.stringify(lockInfo, null, 2), { encoding: 'utf8', flag: 'wx' });
             lockHeld = true;
           } catch { // intentional: lock contention, skip task
+            // Counts against the budget — see note on `countedTowardLimit`.
             results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'skipped_locked' });
             continue;
           }
         } else {
-          // Requeue to avoid task loss since dequeueNextTask already advanced the queue cursor.
-          await enqueueTask(teamDir, agentId, {
-            teamId,
+          // The lock is still live and held by another worker. The cursor has
+          // already advanced past this task, so under naive logic we'd lose it.
+          // Re-enqueue — but ONLY if no equivalent task is already pending.
+          // Otherwise repeated ticks against a stuck lock would pile up dozens
+          // of duplicates for the same {runId, nodeId}.
+          const alreadyPending = await hasPendingTaskFor(teamDir, agentId, {
             runId: task.runId,
             nodeId: task.nodeId,
-            kind: 'execute_node',
           });
+          if (!alreadyPending) {
+            await enqueueTask(teamDir, agentId, {
+              teamId,
+              runId: task.runId,
+              nodeId: task.nodeId,
+              kind: 'execute_node',
+            });
+          }
+          // Counts against the budget — see note on `countedTowardLimit`.
           results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'skipped_locked' });
           continue;
         }
@@ -678,6 +715,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         currentlyRunnableIdx === null ||
         String(workflow.nodes[currentlyRunnableIdx]?.id ?? '') !== String(node.id)
       ) {
+        countedTowardLimit = false;
         results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'skipped_stale' });
         continue;
       }
@@ -739,77 +777,8 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
       await ensureDir(path.dirname(nodeOutputAbs));
 
       const promptRaw = promptTemplateInline ? promptTemplateInline : await readTextFile(promptPathAbs);
-      
-      // Build template variables (same as fs.write/fs.append)
-      const vars = {
-        date: new Date().toISOString(),
-        'run.id': runId,
-        'run.timestamp': runId,
-        'workflow.id': String(workflow.id ?? ''),
-        'workflow.name': String(workflow.name ?? workflow.id ?? workflowFile),
-      };
-
-      // Load node outputs and make them available as template variables
-      const { run: runSnap } = await loadRunFile(teamDir, runsDir, task.runId);
 
-      // Expose triggerInput as template variables (for handoff-injected data)
-      if (runSnap.triggerInput && typeof runSnap.triggerInput === 'object') {
-        for (const [key, value] of Object.entries(runSnap.triggerInput)) {
-          if (typeof value === 'string') {
-            vars[`trigger.${key}`] = value;
-          } else if (value !== null && value !== undefined) {
-            vars[`trigger.${key}`] = JSON.stringify(value);
-          }
-        }
-      }
-      for (const nr of (runSnap.nodeResults ?? [])) {
-        const nid = String((nr as Record<string, unknown>).nodeId ?? '');
-        const nrOutPath = String((nr as Record<string, unknown>).nodeOutputPath ?? '');
-        if (nid && nrOutPath) {
-          try {
-            const outAbs = path.resolve(teamDir, nrOutPath);
-            const outputContent = await fs.readFile(outAbs, 'utf8');
-            vars[`${nid}.output`] = outputContent;
-            
-            // Parse JSON outputs and make fields accessible
-            try {
-              const parsed = JSON.parse(outputContent.trim());
-              if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                for (const [key, value] of Object.entries(parsed)) {
-                  if (typeof value === 'string') {
-                    vars[`${nid}.${key}`] = value;
-                    
-                    // Special handling for 'text' field - try to parse as nested JSON
-                    if (key === 'text') {
-                      try {
-                        const nestedParsed = JSON.parse(value);
-                        if (nestedParsed && typeof nestedParsed === 'object' && !Array.isArray(nestedParsed)) {
-                          for (const [nestedKey, nestedValue] of Object.entries(nestedParsed)) {
-                            if (typeof nestedValue === 'string') {
-                              vars[`${nid}.${nestedKey}`] = nestedValue;
-                            } else if (nestedValue !== null && nestedValue !== undefined) {
-                              vars[`${nid}.${nestedKey}_json`] = JSON.stringify(nestedValue);
-                            }
-                          }
-                        }
-                      } catch {
-                        // If nested parsing fails, just keep the text field as is
-                      }
-                    }
-                  } else if (value !== null && value !== undefined) {
-                    // For non-string values, provide JSON representation
-                    vars[`${nid}.${key}_json`] = JSON.stringify(value);
-                  }
-                }
-              }
-            } catch {
-              // If output isn't valid JSON, skip parsing but keep raw output
-            }
-          } catch { /* node output may not exist */ }
-        }
-      }
-      
-      // Apply template variable replacement
+      const vars = await buildTemplateVars(teamDir, runsDir, runId, workflowFile, workflow);
       const prompt = templateReplace(promptRaw, vars);
 
       // Build output format instructions from outputFields when defined
@@ -1071,7 +1040,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         `\nReply with:`,
         `- approve ${code}`,
         `- decline ${code} <what to change>`,
-        `\n(You can also review in Kitchen: http://localhost:7777/teams/${teamId}/workflows/${workflow.id ?? ''})`,
+        `\n(You can also review in Kitchen: ${process.env['CK_BASE_URL'] || 'http://localhost:7777'}/teams/${teamId}/workflows/${workflow.id ?? ''})`,
       ].join('\n');
 
       await toolsInvoke<ToolTextResult>(api, {
@@ -1114,61 +1083,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           if (!relPathRaw) throw new Error('fs.append requires args.path');
           if (!contentRaw) throw new Error('fs.append requires args.content');
 
-          const vars = {
-            date: new Date().toISOString(),
-            'run.id': runId,
-            'workflow.id': String(workflow.id ?? ''),
-            'workflow.name': String(workflow.name ?? workflow.id ?? workflowFile),
-          };
-
-          // Load node outputs (same as fs.write)
-          const { run: runSnap } = await loadRunFile(teamDir, runsDir, task.runId);
-          for (const nr of (runSnap.nodeResults ?? [])) {
-            const nid = String((nr as Record<string, unknown>).nodeId ?? '');
-            const nrOutPath = String((nr as Record<string, unknown>).nodeOutputPath ?? '');
-            if (nid && nrOutPath) {
-              try {
-                const outAbs = path.resolve(teamDir, nrOutPath);
-                const outputContent = await fs.readFile(outAbs, 'utf8');
-                vars[`${nid}.output`] = outputContent;
-                
-                // Parse JSON outputs and make fields accessible
-                try {
-                  const parsed = JSON.parse(outputContent.trim());
-                  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                    for (const [key, value] of Object.entries(parsed)) {
-                      if (typeof value === 'string') {
-                        vars[`${nid}.${key}`] = value;
-                        
-                        // Special handling for 'text' field - try to parse as nested JSON
-                        if (key === 'text') {
-                          try {
-                            const nestedParsed = JSON.parse(value);
-                            if (nestedParsed && typeof nestedParsed === 'object' && !Array.isArray(nestedParsed)) {
-                              for (const [nestedKey, nestedValue] of Object.entries(nestedParsed)) {
-                                if (typeof nestedValue === 'string') {
-                                  vars[`${nid}.${nestedKey}`] = nestedValue;
-                                } else if (nestedValue !== null && nestedValue !== undefined) {
-                                  vars[`${nid}.${nestedKey}_json`] = JSON.stringify(nestedValue);
-                                }
-                              }
-                            }
-                          } catch {
-                            // If nested parsing fails, just keep the text field as is
-                          }
-                        }
-                      } else if (value !== null && value !== undefined) {
-                        // For non-string values, provide JSON representation
-                        vars[`${nid}.${key}_json`] = JSON.stringify(value);
-                      }
-                    }
-                  }
-                } catch {
-                  // If output isn't valid JSON, skip parsing but keep raw output
-                }
-              } catch { /* node output may not exist */ }
-            }
-          }
+          const vars = await buildTemplateVars(teamDir, runsDir, runId, workflowFile, workflow);
 
           const relPath = templateReplace(relPathRaw, vars);
           const content = templateReplace(contentRaw, vars);
@@ -1184,67 +1099,12 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           const result = { appendedTo: path.relative(teamDir, abs), bytes: Buffer.byteLength(content, 'utf8') };
           await fs.writeFile(artifactPath, JSON.stringify({ ok: true, tool: toolName, args: toolArgs, result }, null, 2) + '\n', 'utf8');
 
-
         } else if (toolName === 'fs.write') {
           const relPathRaw = String(toolArgs.path ?? '').trim();
           const contentRaw = String(toolArgs.content ?? '');
           if (!relPathRaw) throw new Error('fs.write requires args.path');
 
-          const vars = {
-            date: new Date().toISOString(),
-            'run.id': runId,
-            'run.timestamp': runId,
-            'workflow.id': String(workflow.id ?? ''),
-            'workflow.name': String(workflow.name ?? workflow.id ?? workflowFile),
-          };
-          // Also inject node outputs so templates like {{brand_review.output}} resolve
-          const { run: runSnap } = await loadRunFile(teamDir, runsDir, task.runId);
-          for (const nr of (runSnap.nodeResults ?? [])) {
-            const nid = String((nr as Record<string, unknown>).nodeId ?? '');
-            const nrOutPath = String((nr as Record<string, unknown>).nodeOutputPath ?? '');
-            if (nid && nrOutPath) {
-              try {
-                const outAbs = path.resolve(teamDir, nrOutPath);
-                const outputContent = await fs.readFile(outAbs, 'utf8');
-                vars[`${nid}.output`] = outputContent;
-                
-                // Parse JSON outputs and make fields accessible
-                try {
-                  const parsed = JSON.parse(outputContent.trim());
-                  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                    for (const [key, value] of Object.entries(parsed)) {
-                      if (typeof value === 'string') {
-                        vars[`${nid}.${key}`] = value;
-                        
-                        // Special handling for 'text' field - try to parse as nested JSON
-                        if (key === 'text') {
-                          try {
-                            const nestedParsed = JSON.parse(value);
-                            if (nestedParsed && typeof nestedParsed === 'object' && !Array.isArray(nestedParsed)) {
-                              for (const [nestedKey, nestedValue] of Object.entries(nestedParsed)) {
-                                if (typeof nestedValue === 'string') {
-                                  vars[`${nid}.${nestedKey}`] = nestedValue;
-                                } else if (nestedValue !== null && nestedValue !== undefined) {
-                                  vars[`${nid}.${nestedKey}_json`] = JSON.stringify(nestedValue);
-                                }
-                              }
-                            }
-                          } catch {
-                            // If nested parsing fails, just keep the text field as is
-                          }
-                        }
-                      } else if (value !== null && value !== undefined) {
-                        // For non-string values, provide JSON representation
-                        vars[`${nid}.${key}_json`] = JSON.stringify(value);
-                      }
-                    }
-                  }
-                } catch {
-                  // If output isn't valid JSON, skip parsing but keep raw output
-                }
-              } catch { /* node output may not exist */ }
-            }
-          }
+          const vars = await buildTemplateVars(teamDir, runsDir, runId, workflowFile, workflow);
           const relPath = templateReplace(relPathRaw, vars);
           const content = templateReplace(contentRaw, vars);
 
@@ -1260,75 +1120,8 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           await fs.writeFile(artifactPath, JSON.stringify({ ok: true, tool: toolName, args: toolArgs, result }, null, 2) + '\n', 'utf8');
 
         } else {
-          // Build template variables for general tool nodes (same as fs.write/fs.append)
-          const vars = {
-            date: new Date().toISOString(),
-            'run.id': runId,
-            'run.timestamp': runId,
-            'workflow.id': String(workflow.id ?? ''),
-            'workflow.name': String(workflow.name ?? workflow.id ?? workflowFile),
-          };
+          const vars = await buildTemplateVars(teamDir, runsDir, runId, workflowFile, workflow);
 
-          // Load node outputs and make them available as template variables
-          const { run: runSnap } = await loadRunFile(teamDir, runsDir, task.runId);
-
-          // Expose triggerInput as template variables (for handoff-injected data)
-          if (runSnap.triggerInput && typeof runSnap.triggerInput === 'object') {
-            for (const [key, value] of Object.entries(runSnap.triggerInput)) {
-              if (typeof value === 'string') {
-                vars[`trigger.${key}`] = value;
-              } else if (value !== null && value !== undefined) {
-                vars[`trigger.${key}`] = JSON.stringify(value);
-              }
-            }
-          }
-          for (const nr of (runSnap.nodeResults ?? [])) {
-            const nid = String((nr as Record<string, unknown>).nodeId ?? '');
-            const nrOutPath = String((nr as Record<string, unknown>).nodeOutputPath ?? '');
-            if (nid && nrOutPath) {
-              try {
-                const outAbs = path.resolve(teamDir, nrOutPath);
-                const outputContent = await fs.readFile(outAbs, 'utf8');
-                vars[`${nid}.output`] = outputContent;
-                
-                // Parse JSON outputs and make fields accessible
-                try {
-                  const parsed = JSON.parse(outputContent.trim());
-                  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                    for (const [key, value] of Object.entries(parsed)) {
-                      if (typeof value === 'string') {
-                        vars[`${nid}.${key}`] = value;
-                        
-                        // Special handling for 'text' field - try to parse as nested JSON
-                        if (key === 'text') {
-                          try {
-                            const nestedParsed = JSON.parse(value);
-                            if (nestedParsed && typeof nestedParsed === 'object' && !Array.isArray(nestedParsed)) {
-                              for (const [nestedKey, nestedValue] of Object.entries(nestedParsed)) {
-                                if (typeof nestedValue === 'string') {
-                                  vars[`${nid}.${nestedKey}`] = nestedValue;
-                                } else if (nestedValue !== null && nestedValue !== undefined) {
-                                  vars[`${nid}.${nestedKey}_json`] = JSON.stringify(nestedValue);
-                                }
-                              }
-                            }
-                          } catch {
-                            // If nested parsing fails, just keep the text field as is
-                          }
-                        }
-                      } else if (value !== null && value !== undefined) {
-                        // For non-string values, provide JSON representation
-                        vars[`${nid}.${key}_json`] = JSON.stringify(value);
-                      }
-                    }
-                  }
-                } catch {
-                  // If output isn't valid JSON, skip parsing but keep raw output
-                }
-              } catch { /* node output may not exist */ }
-            }
-          }
-          
           // Apply template variable replacement to all string values in toolArgs
           const processedToolArgs: Record<string, unknown> = {};
           for (const [key, value] of Object.entries(toolArgs)) {
@@ -1357,13 +1150,20 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
             // to most workflow worker sessions.
             const command = String((processedToolArgs as Record<string, unknown>).command ?? '');
             const workdir = String((processedToolArgs as Record<string, unknown>).workdir ?? teamDir);
-            const timeoutSec = Number((processedToolArgs as Record<string, unknown>).timeout) || 120;
+            // Timeout priority: args.timeout (seconds) > config.timeoutMs (ms) > 120s default
+            const nodeConfig = asRecord((node as unknown as Record<string, unknown>)['config']);
+            const argsTimeoutSec = Number((processedToolArgs as Record<string, unknown>).timeout) || 0;
+            const configTimeoutMs = Number(nodeConfig['timeoutMs']) || 0;
+            const timeoutSec = argsTimeoutSec || (configTimeoutMs > 0 ? Math.ceil(configTimeoutMs / 1000) : 120);
             const result = await api.runtime.system.runCommandWithTimeout(
               ['bash', '-c', command],
               { timeoutMs: timeoutSec * 1000, cwd: workdir },
             );
             if (result.code !== 0) {
-              throw new Error(`exec failed (code=${result.code}):\n${result.stderr || result.stdout}`);
+              const stderr = String(result.stderr ?? '').trim();
+              const stdout = String(result.stdout ?? '').trim();
+              const combined = [stderr, stdout].filter(Boolean).join('\n---stdout---\n');
+              throw new Error(`exec failed (code=${result.code}):\n${combined}`);
             }
             toolRes = { stdout: result.stdout, stderr: result.stderr, code: result.code };
           } else {
@@ -1887,6 +1687,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
       } catch { // intentional: best-effort claim release
         // ignore
       }
+      if (countedTowardLimit) executedCount++;
     }
 
   }