openclaw-node-harness 2.0.4 → 2.1.0

package/bin/mesh-agent.js

@@ -41,6 +41,9 @@ const os = require('os');
 const path = require('path');
 const fs = require('fs');
 const { getActivityState, getSessionInfo } = require('../lib/agent-activity');
+const { loadAllRules, matchRules, formatRulesForPrompt, detectFrameworks, activateFrameworkRules } = require('../lib/rule-loader');
+const { loadHarnessRules, runMeshHarness, runPostCommitValidation, formatHarnessForPrompt } = require('../lib/mesh-harness');
+const { findRole, formatRoleForPrompt } = require('../lib/role-loader');
 
 const sc = StringCodec();
 const { NATS_URL } = require('../lib/nats-resolve');
@@ -51,6 +54,75 @@ const MAX_ATTEMPTS = parseInt(process.env.MESH_MAX_ATTEMPTS || '3');
 const HEARTBEAT_INTERVAL = parseInt(process.env.MESH_HEARTBEAT_INTERVAL || '60000'); // 60s heartbeat
 const WORKSPACE = process.env.MESH_WORKSPACE || path.join(process.env.HOME, '.openclaw', 'workspace');
 
+// ── Rule loading (cached at startup, framework-filtered) ─────────────────
+const RULES_DIR = process.env.OPENCLAW_RULES_DIR || path.join(process.env.HOME, '.openclaw', 'rules');
+const HARNESS_PATH = process.env.OPENCLAW_HARNESS_RULES || path.join(process.env.HOME, '.openclaw', 'harness-rules.json');
+let cachedRules = null;
+let cachedHarnessRules = null;
+
+function getRules() {
+  if (!cachedRules) {
+    const allRules = loadAllRules(RULES_DIR);
+    const detected = detectFrameworks(WORKSPACE);
+    cachedRules = activateFrameworkRules(allRules, detected);
+  }
+  return cachedRules;
+}
+
+function getHarnessRules() {
+  if (!cachedHarnessRules) {
+    cachedHarnessRules = loadHarnessRules(HARNESS_PATH, 'mesh');
+  }
+  return cachedHarnessRules;
+}
+
+/**
+ * Inject matching coding rules into a prompt parts array based on task scope.
+ */
+function injectRules(parts, scope) {
+  // Path-scoped coding standards
+  const matched = matchRules(getRules(), scope || []);
+  if (matched.length > 0) {
+    parts.push(formatRulesForPrompt(matched));
+    parts.push('');
+  }
+
+  // Harness behavioral rules (soft enforcement — LLM-agnostic prompt injection)
+  const harnessText = formatHarnessForPrompt(getHarnessRules());
+  if (harnessText) {
+    parts.push(harnessText);
+    parts.push('');
+  }
+}
+
+// ── Role loading (cached per role ID) ─────────────────
+const ROLE_DIRS = [
+  path.join(process.env.HOME, '.openclaw', 'roles'),
+  path.join(__dirname, '..', 'config', 'roles'),
+];
+const roleCache = new Map();
+
+function getRole(roleId) {
+  if (!roleId) return null;
+  if (roleCache.has(roleId)) return roleCache.get(roleId);
+  const role = findRole(roleId, ROLE_DIRS);
+  if (role) roleCache.set(roleId, role);
+  return role;
+}
+
+/**
+ * Inject role profile into prompt parts array.
+ */
+function injectRole(parts, roleId) {
+  const role = getRole(roleId);
+  if (!role) return;
+  const roleText = formatRoleForPrompt(role);
+  if (roleText) {
+    parts.push(roleText);
+    parts.push('');
+  }
+}
+
 // ── CLI args ──────────────────────────────────────────
 
 const args = process.argv.slice(2);
@@ -141,6 +213,12 @@ function buildInitialPrompt(task) {
     parts.push('');
   }
 
+  // Inject path-scoped coding rules matching task scope
+  injectRules(parts, task.scope);
+
+  // Inject role profile (responsibilities, boundaries, framework)
+  injectRole(parts, task.role);
+
   parts.push('## Instructions');
   parts.push('- Read the relevant files before making changes.');
   parts.push('- Make minimal, focused changes. Do not add scope beyond what is asked.');
@@ -200,6 +278,12 @@ function buildRetryPrompt(task, previousAttempts, attemptNumber) {
     parts.push('');
   }
 
+  // Inject path-scoped coding rules matching task scope
+  injectRules(parts, task.scope);
+
+  // Inject role profile (responsibilities, boundaries, framework)
+  injectRole(parts, task.role);
+
   parts.push('## Instructions');
   parts.push('- Do NOT repeat a failed approach. Try something different.');
   parts.push('- Read the relevant files before making changes.');
@@ -284,6 +368,13 @@ function commitAndMergeWorktree(worktreePath, taskId, summary) {
     // Stage and commit all changes
     execSync('git add -A', { cwd: worktreePath, timeout: 10000, stdio: 'pipe' });
     const commitMsg = `mesh(${taskId}): ${(summary || 'task completed').slice(0, 72)}`;
+
+    // Pre-commit validation: check conventional commit format before committing
+    const conventionalPattern = /^(feat|fix|docs|style|refactor|test|chore|build|ci|perf|revert|mesh)(\(.+\))?: .+/;
+    if (!conventionalPattern.test(commitMsg)) {
+      log(`WARNING: commit message doesn't follow conventional format: "${commitMsg}"`);
+    }
+
     execSync(`git commit -m "${commitMsg.replace(/"/g, '\\"')}"`, {
       cwd: worktreePath, timeout: 10000, stdio: 'pipe',
     });
@@ -510,6 +601,11 @@ function buildCollabPrompt(task, roundNumber, sharedIntel, myScope, myRole) {
     }
   }
 
+  // Inject path-scoped coding rules matching task scope
+  const collabScope = Array.isArray(myScope) ? myScope.map(s => s.replace('[REVIEW-ONLY] ', '')) : task.scope;
+  injectRules(parts, collabScope);
+  injectRole(parts, task.role);
+
   if (task.success_criteria && task.success_criteria.length > 0) {
     parts.push('## Success Criteria');
     for (const c of task.success_criteria) {
@@ -625,6 +721,207 @@ function parseReflection(output) {
   };
 }
 
+// ── Circling Strategy: Prompt Builder + Parser ───────
+
+/**
+ * Build a prompt for a circling strategy step.
+ * Role-specific: Worker gets different instructions than Reviewers at each step.
+ */
+function buildCirclingPrompt(task, circlingData) {
+  const { circling_phase, circling_step, circling_subround, directed_input, my_role } = circlingData;
+  const isWorker = my_role === 'worker';
+  const parts = [];
+
+  parts.push(`# Task: ${task.title}`);
+  parts.push('');
+
+  switch (circling_phase) {
+    case 'init':
+      if (isWorker) {
+        parts.push('## Your Role: WORKER (Central Authority)');
+        parts.push('');
+        parts.push('You are the Worker in a Circling Strategy collaboration. You OWN the deliverable.');
+        parts.push('Produce your initial work artifact (v0) — your first draft/implementation based on the task plan below.');
+        parts.push('');
+      } else {
+        parts.push('## Your Role: REVIEWER');
+        parts.push('');
+        parts.push('You are a Reviewer in a Circling Strategy collaboration.');
+        parts.push('Produce your **reviewStrategy** — your methodology and focus areas for reviewing this type of work.');
+        parts.push('Define: what you will look for, what frameworks you will apply, what your evaluation criteria are.');
+        parts.push('');
+      }
+      break;
+
+    case 'circling':
+      if (circling_step === 1) {
+        // Step 1 — Review Pass
+        parts.push(`## Sub-Round ${circling_subround}, Step 1: Review Pass`);
+        parts.push('');
+        if (isWorker) {
+          parts.push('## Your Role: WORKER — Analyze Review Strategies');
+          parts.push('');
+          parts.push('Below are the review STRATEGIES from both reviewers (NOT their review findings).');
+          parts.push('Analyze each strategy: what they focus on well, what they miss, how they could improve.');
+          parts.push('Your feedback will help reviewers sharpen their approaches.');
+          parts.push('Do NOT touch the work artifact in this step.');
+          parts.push('');
+        } else {
+          parts.push('## Your Role: REVIEWER — Review the Work Artifact');
+          parts.push('');
+          parts.push('Below is the work artifact. Review it using your review strategy.');
+          parts.push('Produce concrete, actionable findings. For each finding, specify:');
+          parts.push('- What you found (the issue or observation)');
+          parts.push('- Where in the artifact (location/line/section)');
+          parts.push('- Why it matters (impact)');
+          parts.push('- What you recommend (suggested fix or improvement)');
+          parts.push('');
+        }
+      } else if (circling_step === 2) {
+        // Step 2 — Integration + Refinement
+        parts.push(`## Sub-Round ${circling_subround}, Step 2: Integration & Refinement`);
+        parts.push('');
+        if (isWorker) {
+          parts.push('## Your Role: WORKER — Judge Reviews & Update Artifact');
+          parts.push('');
+          parts.push('Below are the review artifacts from both reviewers.');
+          parts.push('For EACH review finding, judge it:');
+          parts.push('- **ACCEPTED**: implement the suggestion and note where');
+          parts.push('- **REJECTED**: explain why with reasoning');
+          parts.push('- **MODIFIED**: implement differently and explain why');
+          parts.push('');
+          parts.push('Then produce your UPDATED work artifact incorporating accepted changes.');
+          parts.push('Also produce a reconciliationDoc summarizing all judgments.');
+          parts.push('');
+          parts.push('You must output TWO artifacts using the multi-artifact format below.');
+          parts.push('');
+        } else {
+          parts.push('## Your Role: REVIEWER — Refine Your Strategy');
+          parts.push('');
+          parts.push("Below is the Worker's analysis of your review strategy (and the other reviewer's).");
+          parts.push("Evaluate the Worker's feedback honestly:");
+          parts.push("- If the feedback is valid, adjust your strategy accordingly");
+          parts.push("- If you disagree, explain why and keep your approach");
+          parts.push('Produce your REFINED reviewStrategy.');
+          parts.push('');
+        }
+      }
+      break;
+
+    case 'finalization':
+      parts.push('## FINALIZATION');
+      parts.push('');
+      if (isWorker) {
+        parts.push('## Your Role: WORKER — Final Delivery');
+        parts.push('');
+        parts.push('Produce your FINAL formatted work artifact.');
+        parts.push('Also produce a completionDiff — a checklist comparing original plan items vs what was delivered:');
+        parts.push('  [x] Item implemented');
+        parts.push('  [ ] Item NOT implemented — reason / deferred to follow-up');
+        parts.push('');
+        parts.push('You must output TWO artifacts using the multi-artifact format below.');
+        parts.push('');
+      } else {
+        parts.push('## Your Role: REVIEWER — Final Sign-Off');
+        parts.push('');
+        parts.push('Review the final work artifact against the original task plan.');
+        parts.push('Either:');
+        parts.push('- **APPROVE**: vote "converged" — the work meets quality standards');
+        parts.push('- **FLAG CONCERN**: vote "blocked" — describe remaining critical concerns');
+        parts.push('');
+      }
+      break;
+  }
+
+  // Add directed input
+  if (directed_input) {
+    parts.push('---');
+    parts.push('');
+    parts.push(directed_input);
+    parts.push('');
+  }
+
+  // Add artifact output instructions
+  const isMultiArtifact = isWorker && (circling_step === 2 || circling_phase === 'finalization');
+  parts.push('---');
+  parts.push('');
+
+  if (isMultiArtifact) {
+    // Multi-artifact output format (Worker Step 2 and Finalization)
+    const art1Type = circling_phase === 'finalization' ? 'workArtifact' : 'workArtifact';
+    const art2Type = circling_phase === 'finalization' ? 'completionDiff' : 'reconciliationDoc';
+
+    parts.push('## Output Format (TWO artifacts required)');
+    parts.push('');
+    parts.push('Produce your first artifact, then wrap it:');
+    parts.push('');
+    parts.push('===CIRCLING_ARTIFACT===');
+    parts.push(`type: ${art1Type}`);
+    parts.push('===END_ARTIFACT===');
+    parts.push('');
+    parts.push('Then produce your second artifact:');
+    parts.push('');
+    parts.push('===CIRCLING_ARTIFACT===');
+    parts.push(`type: ${art2Type}`);
+    parts.push('===END_ARTIFACT===');
+    parts.push('');
+    parts.push('Then end with:');
+  } else {
+    parts.push('## Output Format');
+    parts.push('');
+    parts.push('Produce your work above, then end with:');
+  }
+
+  // Determine the correct type for single-artifact output
+  let artifactType = 'workArtifact'; // default
+  if (!isWorker) {
+    if (circling_phase === 'init' || circling_step === 2) artifactType = 'reviewStrategy';
+    else if (circling_step === 1) artifactType = 'reviewArtifact';
+    else if (circling_phase === 'finalization') artifactType = 'reviewSignOff';
+  } else {
+    if (circling_step === 1) artifactType = 'workerReviewsAnalysis';
+  }
+
+  parts.push('');
+  parts.push('===CIRCLING_REFLECTION===');
+  parts.push(`type: ${artifactType}`);
+  parts.push('summary: [1-2 sentences about what you did]');
+  parts.push('confidence: [0.0 to 1.0]');
+  if (circling_phase === 'finalization') {
+    parts.push('vote: [converged|blocked]');
+  } else {
+    parts.push('vote: [continue|converged|blocked]');
+  }
+  parts.push('===END_REFLECTION===');
+  parts.push('');
+  parts.push('Rules:');
+  parts.push('- Begin your output with the artifact content DIRECTLY. Do NOT include any preamble, explanation, or commentary before the artifact. Any text before the artifact delimiters (or before the reflection block for single-artifact output) is treated as part of the artifact.');
+  parts.push('- confidence: a number between 0.0 and 1.0');
+  if (circling_phase === 'finalization') {
+    parts.push('- vote: "converged" (work meets quality standards) or "blocked" (critical issue remains)');
+  } else {
+    parts.push('- vote: "continue" (more work needed), "converged" (satisfied), or "blocked" (critical issue)');
+  }
+  parts.push('- The reflection block MUST be the last thing in your response');
+
+  return parts.join('\n');
+}
+
+// Parser extracted to lib/circling-parser.js — single source of truth for both
+// production code and tests. Zero external dependencies.
+const { parseCirclingReflection: _parseCircling } = require('../lib/circling-parser');
+
+/**
+ * Parse a circling strategy output. Delegates to lib/circling-parser.js
+ * with agent-specific options (logger, legacy fallback).
+ */
+function parseCirclingReflection(output) {
+  return _parseCircling(output, {
+    log: (msg) => log(msg),
+    legacyParser: parseReflection,
+  });
+}
+
 // ── Collaborative Task Execution ──────────────────────
 
 /**
@@ -736,32 +1033,60 @@ async function executeCollabTask(task) {
       if (roundsDone) break;
 
       const roundData = JSON.parse(sc.decode(roundMsg.data));
-      const { round_number, shared_intel, my_scope, my_role, mode, current_turn } = roundData;
+      const { round_number, shared_intel, directed_input, my_scope, my_role, mode, current_turn,
+              circling_phase, circling_step, circling_subround } = roundData;
 
       // Sequential mode safety guard: skip if it's not our turn.
-      // The daemon (notifySequentialTurn) only sends to the current-turn node,
-      // so this should not normally trigger. Kept as a defensive check.
       if (mode === 'sequential' && current_turn && current_turn !== NODE_ID) {
         log(`COLLAB R${round_number}: Not our turn (current: ${current_turn}). Waiting.`);
         continue;
       }
 
-      log(`COLLAB R${round_number}: Starting work (role: ${my_role}, scope: ${JSON.stringify(my_scope)})`);
+      const isCircling = mode === 'circling_strategy';
+      const stepLabel = isCircling
+        ? `${circling_phase === 'init' ? 'Init' : circling_phase === 'finalization' ? 'Final' : `SR${circling_subround}/S${circling_step}`}`
+        : `R${round_number}`;
+      log(`COLLAB ${stepLabel}: Starting work (role: ${my_role}, scope: ${JSON.stringify(my_scope)})`);
 
-      // Build round-specific prompt
-      const prompt = buildCollabPrompt(task, round_number, shared_intel, my_scope, my_role);
+      // Build prompt — circling uses directed inputs, other modes use shared intel
+      const prompt = isCircling
+        ? buildCirclingPrompt(task, roundData)
+        : buildCollabPrompt(task, round_number, shared_intel, my_scope, my_role);
 
       if (DRY_RUN) {
         log(`[DRY RUN] Collab prompt:\n${prompt}`);
         break;
       }
 
-      // Execute Claude
+      // Execute provider (LLM or shell)
       const llmResult = await runLLM(prompt, task, worktreePath);
       const output = llmResult.stdout || '';
 
-      // Parse reflection from output
-      const reflection = parseReflection(output);
+      // Parse reflection — circling uses delimiter-based parser, others use JSON-block parser
+      let reflection;
+      let circlingArtifacts = [];
+
+      if (llmResult.provider === 'shell') {
+        reflection = {
+          summary: output.trim().slice(-500) || '(no output)',
+          learnings: '',
+          confidence: llmResult.exitCode === 0 ? 1.0 : 0.0,
+          vote: llmResult.exitCode === 0 ? 'converged' : 'continue',
+          parse_failed: false,
+        };
+      } else if (isCircling) {
+        const circResult = parseCirclingReflection(output);
+        reflection = {
+          summary: circResult.summary,
+          learnings: '',
+          confidence: circResult.confidence,
+          vote: circResult.vote,
+          parse_failed: circResult.parse_failed,
+        };
+        circlingArtifacts = circResult.circling_artifacts;
+      } else {
+        reflection = parseReflection(output);
+      }
 
       // List modified files
       let artifacts = [];
@@ -781,16 +1106,20 @@ async function executeCollabTask(task) {
           node_id: NODE_ID,
           round: round_number,
           summary: reflection.summary,
-          learnings: reflection.learnings,
+          learnings: reflection.learnings || '',
           artifacts,
           confidence: reflection.confidence,
           vote: reflection.vote,
           parse_failed: reflection.parse_failed,
+          // Circling extensions
+          circling_step: isCircling ? circling_step : null,
+          circling_artifacts: circlingArtifacts,
         });
         const parseTag = reflection.parse_failed ? ' [PARSE FAILED]' : '';
-        log(`COLLAB R${round_number}: Reflection submitted (vote: ${reflection.vote}, conf: ${reflection.confidence}${parseTag})`);
+        const artCount = circlingArtifacts.length > 0 ? `, ${circlingArtifacts.length} artifact(s)` : '';
+        log(`COLLAB ${stepLabel}: Reflection submitted (vote: ${reflection.vote}, conf: ${reflection.confidence}${parseTag}${artCount})`);
       } catch (err) {
-        log(`COLLAB R${round_number}: Reflection submit failed: ${err.message}`);
+        log(`COLLAB ${stepLabel}: Reflection submit failed: ${err.message}`);
       }
 
       // Check if session is done (converged/completed/aborted)
@@ -897,6 +1226,48 @@ async function executeTask(task) {
       continue;
     }
 
+    // ── Mesh Harness: Mechanical Enforcement (LLM-agnostic) ──
+    // Runs AFTER LLM exits successfully, BEFORE commit. This is the hard
+    // enforcement layer — it doesn't depend on the LLM obeying prompt rules.
+    const harnessResult = runMeshHarness({
+      rules: getHarnessRules(),
+      worktreePath,
+      taskScope: task.scope,
+      llmOutput: llmResult.stdout,
+      hasMetric: !!task.metric,
+      log,
+      role: getRole(task.role),
+    });
+
+    if (!harnessResult.pass) {
+      log(`HARNESS BLOCKED: ${harnessResult.violations.length} violation(s)`);
+      for (const v of harnessResult.violations) {
+        log(`  - [${v.rule}] ${v.message}`);
+      }
+      // Scope violations were already reverted by enforceScopeCheck.
+      // Secret violations block the commit entirely.
+      const hasSecrets = harnessResult.violations.some(v => v.rule === 'no-hardcoded-secrets');
+      if (hasSecrets) {
+        const attemptRecord = {
+          approach: `Attempt ${attempt}: harness blocked — secrets detected`,
+          result: harnessResult.violations.map(v => v.message).join('; '),
+          keep: false,
+        };
+        attempts.push(attemptRecord);
+        await natsRequest('mesh.tasks.attempt', { task_id: task.task_id, ...attemptRecord });
+        log(`Attempt ${attempt}: harness blocked commit (secrets). Retrying.`);
+        continue;
+      }
+      // Non-secret violations (scope reverts, output blocks): proceed with warnings
+    }
+
+    if (harnessResult.warnings.length > 0) {
+      log(`HARNESS WARNINGS: ${harnessResult.warnings.length}`);
+      for (const w of harnessResult.warnings) {
+        log(`  - [${w.rule}] ${w.message}`);
+      }
+    }
+
     // If no metric, trust LLM output and complete
     if (!task.metric) {
       const attemptRecord = {
@@ -911,11 +1282,20 @@ async function executeTask(task) {
       const mergeResult = commitAndMergeWorktree(worktreePath, task.task_id, summary);
       const keepBranch = mergeResult && !mergeResult.merged; // keep on merge conflict
 
+      // Post-commit validation (conventional commits, etc.)
+      if (mergeResult?.committed) {
+        runPostCommitValidation(getHarnessRules(), worktreePath, log);
+      }
+
       await natsRequest('mesh.tasks.complete', {
         task_id: task.task_id,
         result: {
           success: true, summary, artifacts: [],
           cost: sessionInfo?.cost || null,
+          harness: {
+            violations: harnessResult.violations,
+            warnings: harnessResult.warnings,
+          },
           sha: mergeResult?.sha || null,
           merged: mergeResult?.merged ?? null,
         },
@@ -943,6 +1323,11 @@ async function executeTask(task) {
       const mergeResult = commitAndMergeWorktree(worktreePath, task.task_id, summary);
       const keepBranch = mergeResult && !mergeResult.merged;
 
+      // Post-commit validation (conventional commits, etc.)
+      if (mergeResult?.committed) {
+        runPostCommitValidation(getHarnessRules(), worktreePath, log);
+      }
+
       await natsRequest('mesh.tasks.complete', {
         task_id: task.task_id,
         result: {
@@ -952,6 +1337,10 @@ async function executeTask(task) {
           cost: sessionInfo?.cost || null,
           sha: mergeResult?.sha || null,
           merged: mergeResult?.merged ?? null,
+          harness: {
+            violations: harnessResult.violations,
+            warnings: harnessResult.warnings,
+          },
         },
       });
       cleanupWorktree(worktreePath, keepBranch);

package/bin/mesh-bridge.js

@@ -285,6 +285,55 @@ function handleCollabEvent(eventType, taskId, data) {
       log(`COLLAB ABORTED: ${taskId} — ${session.result?.summary || 'unknown reason'}`);
       break;
 
+    // Circling Strategy events
+    case 'collab.circling_step_started': {
+      if (!dispatched.has(taskId)) {
+        // Auto-track CLI-submitted circling tasks
+        try {
+          const tasks = readTasks(ACTIVE_TASKS_PATH);
+          if (tasks.find(t => t.task_id === taskId && t.execution === 'mesh')) {
+            dispatched.add(taskId);
+            lastHeartbeat.set(taskId, Date.now());
+            log(`CIRCLING AUTO-TRACK: ${taskId} (CLI-submitted)`);
+          } else { break; }
+        } catch { break; }
+      }
+      const c = session.circling || {};
+      const stepName = c.phase === 'init' ? 'Init'
+        : c.phase === 'finalization' ? 'Finalization'
+        : `SR${c.current_subround}/${c.max_subrounds} Step${c.current_step}`;
+      log(`CIRCLING ${stepName}: started for ${taskId}`);
+      updateTaskInPlace(ACTIVE_TASKS_PATH, taskId, {
+        circling_phase: c.phase || null,
+        circling_subround: c.current_subround || 0,
+        circling_step: c.current_step || 0,
+        next_action: `${stepName} in progress (${session.nodes?.length || '?'} nodes)`,
+        updated_at: isoTimestamp(),
+      });
+      break;
+    }
+
+    case 'collab.circling_gate': {
+      const cg = session.circling || {};
+      // Extract blocked reviewer summaries from the last round (if any)
+      const lastRound = session.rounds?.[session.rounds.length - 1];
+      const blockedVotes = lastRound?.reflections?.filter(r => r.vote === 'blocked') || [];
+      let gateMsg;
+      if (blockedVotes.length > 0) {
+        const reason = blockedVotes.map(r => r.summary).filter(Boolean).join('; ').slice(0, 150);
+        gateMsg = `[GATE] SR${cg.current_subround} blocked — ${reason || 'reviewer flagged concern'}`;
+      } else {
+        gateMsg = `[GATE] SR${cg.current_subround} complete — review reconciliationDoc and approve/reject`;
+      }
+      log(`CIRCLING GATE: ${taskId} — SR${cg.current_subround} waiting for approval`);
+      updateTaskInPlace(ACTIVE_TASKS_PATH, taskId, {
+        status: 'waiting-user',
+        next_action: gateMsg,
+        updated_at: isoTimestamp(),
+      });
+      break;
+    }
+
     default:
       log(`COLLAB EVENT: ${eventType} for ${taskId}`);
   }
@@ -730,6 +779,16 @@ async function main() {
   const stalenessTimer = setInterval(checkStaleness, HEARTBEAT_CHECK_INTERVAL);
   log(`Heartbeat staleness check: every ${HEARTBEAT_CHECK_INTERVAL / 1000}s (warn at ${STALE_WARNING_MS / 60000}m)`);
 
+  // Wake signal — MC publishes mesh.bridge.wake after creating a mesh task
+  // so the bridge picks it up in ~1s instead of waiting for the next poll cycle
+  let wakeResolve = null;
+  const wakeSub = nc.subscribe('mesh.bridge.wake', {
+    callback: () => {
+      log('WAKE: received wake signal, triggering immediate poll');
+      if (wakeResolve) { wakeResolve(); wakeResolve = null; }
+    },
+  });
+
   // Dispatch loop (polls active-tasks.md)
   while (running) {
     try {
@@ -779,10 +838,16 @@ async function main() {
       }
     }
 
-    await new Promise(r => setTimeout(r, DISPATCH_INTERVAL));
+    // Sleep until next poll OR wake signal, whichever comes first
+    await Promise.race([
+      new Promise(r => setTimeout(r, DISPATCH_INTERVAL)),
+      new Promise(r => { wakeResolve = r; }),
+    ]);
+    wakeResolve = null;
   }
 
   clearInterval(stalenessTimer);
+  wakeSub.unsubscribe();
   sub.unsubscribe();
   await nc.drain();
   log('Bridge stopped.');