openclaw-node-harness 2.0.3 → 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',
     });
@@ -294,18 +385,31 @@ function commitAndMergeWorktree(worktreePath, taskId, summary) {
 
     log(`Committed ${sha} on ${branch}: ${commitMsg}`);
 
-    // Merge into main (from workspace)
-    try {
-      execSync(`git merge --no-ff "${branch}" -m "Merge ${branch}: ${taskId}"`, {
-        cwd: WORKSPACE, timeout: 30000, stdio: 'pipe',
-      });
-      log(`Merged ${branch} into main`);
-      return { committed: true, merged: true, sha };
-    } catch (mergeErr) {
-      // Merge conflict — abort and keep branch for human resolution
-      execSync('git merge --abort', { cwd: WORKSPACE, timeout: 5000, stdio: 'ignore' });
-      log(`MERGE CONFLICT on ${branch} — branch kept for manual resolution`);
-      return { committed: true, merged: false, sha };
+    // Merge into main (from workspace).
+    // Parallel collab: multiple nodes may merge concurrently. If the first attempt
+    // fails (e.g., another node merged first), retry once after pulling.
+    const mergeMsg = `Merge ${branch}: ${taskId}`;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        execSync(`git merge --no-ff "${branch}" -m "${mergeMsg.replace(/"/g, '\\"')}"`, {
+          cwd: WORKSPACE, timeout: 30000, stdio: 'pipe',
+        });
+        log(`Merged ${branch} into main${attempt > 0 ? ' (retry succeeded)' : ''}`);
+        return { committed: true, merged: true, sha };
+      } catch (mergeErr) {
+        execSync('git merge --abort', { cwd: WORKSPACE, timeout: 5000, stdio: 'ignore' });
+        if (attempt === 0) {
+          // First failure: pull and retry (handles race with parallel merge)
+          try {
+            log(`Merge attempt 1 failed for ${branch} — fast-forward pulling and retrying`);
+            execSync('git pull --ff-only', { cwd: WORKSPACE, timeout: 15000, stdio: 'pipe' });
+          } catch { /* best effort pull */ }
+        } else {
+          // Second failure: real conflict — keep branch for human resolution
+          log(`MERGE CONFLICT on ${branch} — branch kept for manual resolution`);
+          return { committed: true, merged: false, sha, conflict: true };
+        }
+      }
     }
   } catch (err) {
     log(`Commit/merge warning: ${err.message}`);
@@ -377,14 +481,23 @@ function runLLM(prompt, task, worktreePath) {
       timeout: (task.budget_minutes || 30) * 60 * 1000, // kill if exceeds budget
     });
 
-    // Heartbeat: signal daemon with activity state
+    // Heartbeat: signal daemon with activity state.
+    // getActivityState reads Claude JSONL files — only useful for Claude provider.
+    // For other providers, send a basic heartbeat (process alive = active).
+    const isClaude = provider.name === 'claude';
     const heartbeatTimer = setInterval(async () => {
       try {
-        const activity = await getActivityState(cleanCwd);
         const payload = { task_id: task.task_id };
-        if (activity) {
-          payload.activity_state = activity.state;
-          payload.activity_timestamp = activity.timestamp?.toISOString();
+        if (isClaude) {
+          const activity = await getActivityState(cleanCwd);
+          if (activity) {
+            payload.activity_state = activity.state;
+            payload.activity_timestamp = activity.timestamp?.toISOString();
+          }
+        } else {
+          // Non-Claude: process is running → active
+          payload.activity_state = 'active';
+          payload.activity_timestamp = new Date().toISOString();
         }
         await natsRequest('mesh.tasks.heartbeat', payload);
       } catch {
@@ -488,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) {
@@ -603,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 ──────────────────────
 
 /**
@@ -649,6 +968,13 @@ async function executeCollabTask(task) {
     return;
   }
 
+  // Subscribe to round notifications BEFORE joining — prevents race condition
+  // where the daemon starts round 1 immediately upon last node joining,
+  // but the joining node hasn't subscribed yet and misses the notification.
+  const roundSub = nc.subscribe(`mesh.collab.${sessionId}.node.${NODE_ID}.round`);
+  let roundsDone = false;
+  let lastKnownSessionStatus = null; // tracks why rounds ended (completed/aborted/converged)
+
   // Join the session using the discovered session_id
   let session;
   try {
@@ -659,6 +985,7 @@ async function executeCollabTask(task) {
     session = joinResult;
   } catch (err) {
     log(`COLLAB JOIN FAILED: ${err.message} (session: ${sessionId})`);
+    roundSub.unsubscribe();
     await natsRequest('mesh.tasks.fail', {
       task_id: task.task_id,
       reason: `Failed to join collab session ${sessionId}: ${err.message}`,
@@ -669,6 +996,7 @@ async function executeCollabTask(task) {
 
   if (!session) {
     log(`COLLAB JOIN RETURNED NULL for session ${sessionId}`);
+    roundSub.unsubscribe();
     await natsRequest('mesh.tasks.fail', {
       task_id: task.task_id,
       reason: `Collab session ${sessionId} rejected join (full, closed, or duplicate node).`,
@@ -684,87 +1012,146 @@ async function executeCollabTask(task) {
   const worktreePath = createWorktree(`${task.task_id}-${NODE_ID}`);
   const taskDir = worktreePath || WORKSPACE;
 
-  // Subscribe to round notifications for this session and this node
-  const roundSub = nc.subscribe(`mesh.collab.${sessionId}.node.${NODE_ID}.round`);
-  let roundsDone = false;
+  // Periodic session heartbeat — detects abort/completion while waiting for rounds
+  const sessionHeartbeat = setInterval(async () => {
+    try {
+      const status = await natsRequest('mesh.collab.status', { session_id: sessionId }, 5000);
+      if (['aborted', 'completed'].includes(status.status)) {
+        log(`COLLAB HEARTBEAT: Session ${sessionId} is ${status.status}. Unsubscribing.`);
+        lastKnownSessionStatus = status.status;
+        roundsDone = true;
+        roundSub.unsubscribe();
+      }
+    } catch { /* best effort */ }
+  }, 10000);
 
   // Signal start
   await natsRequest('mesh.tasks.start', { task_id: task.task_id }).catch(() => {});
 
-  for await (const roundMsg of roundSub) {
-    if (roundsDone) break;
+  try {
+    for await (const roundMsg of roundSub) {
+      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 roundData = JSON.parse(sc.decode(roundMsg.data));
+      const { round_number, shared_intel, directed_input, my_scope, my_role, mode, current_turn,
+              circling_phase, circling_step, circling_subround } = roundData;
 
-    // Sequential mode: skip if it's not our turn
-    if (mode === 'sequential' && current_turn && current_turn !== NODE_ID) {
-      log(`COLLAB R${round_number}: Not our turn (current: ${current_turn}). Waiting.`);
-      continue;
-    }
+      // Sequential mode safety guard: skip if it's not our turn.
+      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;
-    }
+      if (DRY_RUN) {
+        log(`[DRY RUN] Collab prompt:\n${prompt}`);
+        break;
+      }
 
-    // Execute Claude
-    const llmResult = await runLLM(prompt, task, worktreePath);
-    const output = llmResult.stdout || '';
+      // Execute provider (LLM or shell)
+      const llmResult = await runLLM(prompt, task, worktreePath);
+      const output = llmResult.stdout || '';
+
+      // 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);
+      }
 
-    // Parse reflection from output
-    const reflection = parseReflection(output);
+      // List modified files
+      let artifacts = [];
+      try {
+        if (worktreePath) {
+          const status = require('child_process').execSync('git status --porcelain', {
+            cwd: worktreePath, timeout: 5000, encoding: 'utf-8',
+          }).trim();
+          artifacts = status.split('\n').filter(Boolean).map(line => line.slice(3));
+        }
+      } catch { /* best effort */ }
 
-    // List modified files
-    let artifacts = [];
-    try {
-      if (worktreePath) {
-        const status = require('child_process').execSync('git status --porcelain', {
-          cwd: worktreePath, timeout: 5000, encoding: 'utf-8',
-        }).trim();
-        artifacts = status.split('\n').filter(Boolean).map(line => line.slice(3));
+      // Submit reflection
+      try {
+        await natsRequest('mesh.collab.reflect', {
+          session_id: sessionId,
+          node_id: NODE_ID,
+          round: round_number,
+          summary: reflection.summary,
+          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]' : '';
+        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 ${stepLabel}: Reflection submit failed: ${err.message}`);
       }
-    } catch { /* best effort */ }
 
-    // Submit reflection
-    try {
-      await natsRequest('mesh.collab.reflect', {
-        session_id: sessionId,
-        node_id: NODE_ID,
-        round: round_number,
-        summary: reflection.summary,
-        learnings: reflection.learnings,
-        artifacts,
-        confidence: reflection.confidence,
-        vote: reflection.vote,
-        parse_failed: reflection.parse_failed,
-      });
-      const parseTag = reflection.parse_failed ? ' [PARSE FAILED]' : '';
-      log(`COLLAB R${round_number}: Reflection submitted (vote: ${reflection.vote}, conf: ${reflection.confidence}${parseTag})`);
-    } catch (err) {
-      log(`COLLAB R${round_number}: Reflection submit failed: ${err.message}`);
+      // Check if session is done (converged/completed/aborted)
+      try {
+        const status = await natsRequest('mesh.collab.status', { session_id: sessionId });
+        if (['converged', 'completed', 'aborted'].includes(status.status)) {
+          log(`COLLAB: Session ${sessionId} is ${status.status}. Done.`);
+          lastKnownSessionStatus = status.status;
+          roundsDone = true;
+        }
+      } catch { /* continue listening */ }
     }
-
-    // Check if session is done (converged/completed/aborted)
-    try {
-      const status = await natsRequest('mesh.collab.status', { session_id: sessionId });
-      if (['converged', 'completed', 'aborted'].includes(status.status)) {
-        log(`COLLAB: Session ${sessionId} is ${status.status}. Done.`);
-        roundsDone = true;
-      }
-    } catch { /* continue listening */ }
+  } finally {
+    clearInterval(sessionHeartbeat);
+    roundSub.unsubscribe();
   }
 
-  roundSub.unsubscribe();
-
-  // Commit and merge worktree
-  const mergeResult = commitAndMergeWorktree(worktreePath, `${task.task_id}-${NODE_ID}`, `collab contribution from ${NODE_ID}`);
-  cleanupWorktree(worktreePath, mergeResult && !mergeResult?.merged);
+  // Commit and merge only on successful convergence — don't merge partial
+  // work from aborted/failed sessions into main.
+  // Uses lastKnownSessionStatus (set during round loop or heartbeat) instead of
+  // a fresh network read, which could see stale state due to NATS latency.
+  try {
+    if (['completed', 'converged'].includes(lastKnownSessionStatus)) {
+      const mergeResult = commitAndMergeWorktree(worktreePath, `${task.task_id}-${NODE_ID}`, `collab contribution from ${NODE_ID}`);
+      cleanupWorktree(worktreePath, mergeResult && !mergeResult?.merged);
+    } else {
+      log(`COLLAB: Session ${sessionId} ended as ${lastKnownSessionStatus || 'unknown'} — discarding worktree`);
+      cleanupWorktree(worktreePath, false);
+    }
+  } catch (err) {
+    log(`COLLAB WORKTREE CLEANUP FAILED: ${err.message}`);
+  }
 
   writeAgentState('idle', null);
   log(`COLLAB DONE: ${task.task_id} (node: ${NODE_ID})`);
@@ -839,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 = {
@@ -853,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,
         },
@@ -885,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: {
@@ -894,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);
@@ -986,8 +1433,82 @@ async function main() {
   })();
   log(`  Listening: mesh.agent.${NODE_ID}.alive`);
 
+  // Subscribe to collab recruit broadcasts — allows this node to join
+  // collab sessions without being the claiming node
+  const recruitSub = nc.subscribe('mesh.collab.*.recruit');
+  (async () => {
+    for await (const msg of recruitSub) {
+      try {
+        const recruit = JSON.parse(sc.decode(msg.data));
+        if (currentTaskId) continue; // busy
+
+        // Fetch task to check preferences and get collab spec
+        const task = await natsRequest('mesh.tasks.get', { task_id: recruit.task_id }, 5000);
+        if (!task || !task.collaboration) continue;
+        if (task.owner === NODE_ID) continue; // we claimed it, already handling
+
+        // Check preferred_nodes
+        if (task.preferred_nodes && task.preferred_nodes.length > 0) {
+          if (!task.preferred_nodes.includes(NODE_ID)) continue;
+        }
+        // Check exclude_nodes
+        if (task.exclude_nodes && task.exclude_nodes.length > 0) {
+          if (task.exclude_nodes.includes(NODE_ID)) continue;
+        }
+
+        log(`RECRUIT: Joining collab session ${recruit.session_id} for task ${recruit.task_id}`);
+        currentTaskId = task.task_id;
+        await executeCollabTask(task);
+        currentTaskId = null;
+      } catch (err) {
+        log(`RECRUIT ERROR: ${err.message}`);
+        currentTaskId = null;
+      }
+    }
+  })();
+  log(`  Listening: mesh.collab.*.recruit (collab recruiting)`);
+
+  // Also poll for recruiting sessions on idle — catches recruits we missed
+  async function checkRecruitingSessions() {
+    if (currentTaskId) return; // busy
+    try {
+      const sessions = await natsRequest('mesh.collab.recruiting', {}, 5000);
+      if (!sessions || !Array.isArray(sessions) || sessions.length === 0) return;
+
+      for (const s of sessions) {
+        if (currentTaskId) break; // became busy
+        // Skip if we already joined this session
+        if (s.node_ids && s.node_ids.includes(NODE_ID)) continue;
+        // Skip if session is full
+        if (s.max_nodes && s.current_nodes >= s.max_nodes) continue;
+
+        // Fetch task to check preferences
+        const task = await natsRequest('mesh.tasks.get', { task_id: s.task_id }, 5000);
+        if (!task || !task.collaboration) continue;
+        if (task.preferred_nodes && task.preferred_nodes.length > 0) {
+          if (!task.preferred_nodes.includes(NODE_ID)) continue;
+        }
+        if (task.exclude_nodes && task.exclude_nodes.length > 0) {
+          if (task.exclude_nodes.includes(NODE_ID)) continue;
+        }
+
+        log(`RECRUIT POLL: Joining collab session ${s.session_id} for task ${s.task_id}`);
+        currentTaskId = task.task_id;
+        await executeCollabTask(task);
+        currentTaskId = null;
+      }
+    } catch { /* silent — recruiting poll is best-effort */ }
+  }
+
   while (running) {
     try {
+      // Check for recruiting collab sessions before trying to claim
+      await checkRecruitingSessions();
+      if (currentTaskId) {
+        await new Promise(r => setTimeout(r, POLL_INTERVAL));
+        continue;
+      }
+
       // Claim next available task (longer timeout — KV operations on remote NATS can be slow)
       const task = await natsRequest('mesh.tasks.claim', { node_id: NODE_ID }, 60000);
 
@@ -1035,3 +1556,4 @@ main().catch(err => {
   console.error(`[mesh-agent] Fatal: ${err.message}`);
   process.exit(1);
 });
+// deploy-v7f0130b